@coasys/ad4m 0.12.0-rc1-dev.2 → 0.12.0-rc1-dev.3

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 (153) hide show
  1. package/jest.config.js +10 -3
  2. package/lib/index.cjs +6872 -5886
  3. package/lib/index.js +6868 -5874
  4. package/lib/src/Ad4mClient.d.ts +9 -16
  5. package/lib/src/Ad4mClient.js +46 -25
  6. package/lib/src/Literal.d.ts +1 -2
  7. package/lib/src/Literal.js +38 -35
  8. package/lib/src/SmartLiteral.d.ts +1 -2
  9. package/lib/src/SmartLiteral.js +30 -15
  10. package/lib/src/agent/AgentClient.d.ts +1 -4
  11. package/lib/src/agent/AgentClient.js +79 -99
  12. package/lib/src/ai/AIClient.d.ts +1 -2
  13. package/lib/src/ai/AIClient.js +224 -220
  14. package/lib/src/expression/ExpressionClient.d.ts +1 -1
  15. package/lib/src/expression/ExpressionClient.js +73 -86
  16. package/lib/src/index.d.ts +1 -1
  17. package/lib/src/index.js +1 -1
  18. package/lib/src/language/LanguageClient.d.ts +1 -1
  19. package/lib/src/language/LanguageClient.js +52 -52
  20. package/lib/src/model/Ad4mModel.d.ts +1351 -144
  21. package/lib/src/model/Ad4mModel.js +3737 -228
  22. package/lib/src/model/Ad4mModel.test.js +522 -979
  23. package/lib/src/model/Subject.d.ts +3 -3
  24. package/lib/src/model/Subject.js +25 -25
  25. package/lib/src/model/decorators.d.ts +444 -100
  26. package/lib/src/model/decorators.js +686 -321
  27. package/lib/src/model/util.d.ts +6 -6
  28. package/lib/src/model/util.js +24 -24
  29. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +1 -5
  30. package/lib/src/neighbourhood/NeighbourhoodClient.js +179 -242
  31. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +1 -2
  32. package/lib/src/neighbourhood/NeighbourhoodProxy.js +28 -13
  33. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +5 -1
  34. package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
  35. package/lib/src/perspectives/PerspectiveClient.js +240 -316
  36. package/lib/src/perspectives/PerspectiveProxy.d.ts +99 -61
  37. package/lib/src/perspectives/PerspectiveProxy.js +485 -832
  38. package/lib/src/runtime/RuntimeClient.d.ts +1 -5
  39. package/lib/src/runtime/RuntimeClient.js +238 -412
  40. package/lib/src/shacl/SHACLFlow.test.js +105 -164
  41. package/lib/src/shacl/SHACLShape.d.ts +12 -17
  42. package/lib/src/shacl/SHACLShape.js +115 -128
  43. package/lib/src/shacl/SHACLShape.test.js +176 -244
  44. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  45. package/lib/src/shims/type-graphql.d.ts +32 -0
  46. package/lib/src/src/Ad4mClient.d.ts +28 -0
  47. package/lib/src/src/Address.d.ts +1 -0
  48. package/lib/src/src/DID.d.ts +1 -0
  49. package/lib/src/src/Exception.d.ts +7 -0
  50. package/lib/src/src/Literal.d.ts +7 -0
  51. package/lib/src/src/PubSub.d.ts +17 -0
  52. package/lib/src/src/SmartLiteral.d.ts +12 -0
  53. package/lib/src/src/agent/Agent.d.ts +110 -0
  54. package/lib/src/src/agent/AgentClient.d.ts +62 -0
  55. package/lib/src/src/agent/AgentResolver.d.ts +30 -0
  56. package/lib/src/src/agent/AgentStatus.d.ts +8 -0
  57. package/lib/src/src/ai/AIClient.d.ts +32 -0
  58. package/lib/src/src/ai/AIResolver.d.ts +75 -0
  59. package/lib/src/src/ai/Tasks.d.ts +37 -0
  60. package/lib/src/src/buildSchema.d.ts +1 -0
  61. package/lib/src/src/expression/Expression.d.ts +28 -0
  62. package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
  63. package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
  64. package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
  65. package/lib/src/src/index.d.ts +35 -0
  66. package/lib/src/src/jestSetup.d.ts +1 -0
  67. package/lib/src/src/language/Icon.d.ts +4 -0
  68. package/lib/src/src/language/Language.d.ts +206 -0
  69. package/lib/src/src/language/LanguageClient.d.ts +17 -0
  70. package/lib/src/src/language/LanguageContext.d.ts +37 -0
  71. package/lib/src/src/language/LanguageHandle.d.ts +9 -0
  72. package/lib/src/src/language/LanguageMeta.d.ts +35 -0
  73. package/lib/src/src/language/LanguageRef.d.ts +6 -0
  74. package/lib/src/src/language/LanguageResolver.d.ts +19 -0
  75. package/lib/src/src/links/Links.d.ts +39 -0
  76. package/lib/src/src/links/Links.test.d.ts +1 -0
  77. package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
  78. package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
  79. package/lib/src/src/model/Subject.d.ts +25 -0
  80. package/lib/src/src/model/decorators.d.ts +545 -0
  81. package/lib/src/src/model/util.d.ts +12 -0
  82. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
  83. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
  84. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
  85. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  86. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
  87. package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
  88. package/lib/src/src/perspectives/Perspective.d.ts +38 -0
  89. package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
  90. package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
  91. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
  92. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
  93. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
  94. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
  95. package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
  96. package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
  97. package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
  98. package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
  99. package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
  100. package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
  101. package/lib/src/src/typeDefs.d.ts +1 -0
  102. package/lib/src/src/unwrapApolloResult.d.ts +2 -0
  103. package/lib/src/src/utils.d.ts +25 -0
  104. package/lib/src/utils.d.ts +0 -8
  105. package/lib/src/utils.js +7 -21
  106. package/package.json +15 -14
  107. package/src/Ad4mClient.test.ts +1315 -1564
  108. package/src/Ad4mClient.ts +54 -55
  109. package/src/Literal.test.ts +26 -45
  110. package/src/Literal.ts +66 -82
  111. package/src/SmartLiteral.ts +58 -74
  112. package/src/agent/AgentClient.ts +99 -144
  113. package/src/ai/AIClient.ts +359 -409
  114. package/src/expression/ExpressionClient.ts +96 -142
  115. package/src/index.ts +1 -1
  116. package/src/language/LanguageClient.ts +113 -137
  117. package/src/model/Ad4mModel.test.ts +616 -1114
  118. package/src/model/Ad4mModel.ts +4361 -451
  119. package/src/model/Subject.ts +159 -0
  120. package/src/model/decorators.ts +1168 -667
  121. package/src/model/util.ts +54 -53
  122. package/src/neighbourhood/NeighbourhoodClient.ts +266 -392
  123. package/src/neighbourhood/NeighbourhoodProxy.test.ts +7 -3
  124. package/src/neighbourhood/NeighbourhoodProxy.ts +40 -58
  125. package/src/perspectives/PerspectiveClient.ts +540 -779
  126. package/src/perspectives/PerspectiveProxy.ts +2067 -2860
  127. package/src/runtime/RuntimeClient.ts +476 -775
  128. package/src/shacl/SHACLFlow.test.ts +129 -196
  129. package/src/shacl/SHACLShape.test.ts +190 -284
  130. package/src/shacl/SHACLShape.ts +200 -224
  131. package/src/utils.ts +17 -31
  132. package/tsconfig.json +10 -9
  133. package/src/model/IMPROVEMENTS.md +0 -482
  134. package/src/model/PREDICATE_COLLISION_FIX.md +0 -651
  135. package/src/model/README.md +0 -317
  136. package/src/model/SHACL_MUTATION_DECOUPLING.md +0 -356
  137. package/src/model/SUBSCRIPTION_STRATEGY.md +0 -317
  138. package/src/model/TC39_STAGE_3_DECORATORS.md +0 -609
  139. package/src/model/mutation.ts +0 -461
  140. package/src/model/parentUtils.ts +0 -91
  141. package/src/model/prolog/generatePrologFacts.ts +0 -176
  142. package/src/model/prolog/index.ts +0 -1
  143. package/src/model/query/ModelQueryBuilder.ts +0 -173
  144. package/src/model/query/fetchInstance.ts +0 -181
  145. package/src/model/query/hydration.ts +0 -273
  146. package/src/model/query/operations.ts +0 -510
  147. package/src/model/query/snapshot.ts +0 -126
  148. package/src/model/query/surrealCompiler.ts +0 -376
  149. package/src/model/schema/fromJSONSchema.ts +0 -411
  150. package/src/model/schema/metadata.ts +0 -148
  151. package/src/model/subscription.ts +0 -307
  152. package/src/model/transaction.ts +0 -60
  153. package/src/model/types.ts +0 -207
@@ -1,273 +0,0 @@
1
- /**
2
- * Shared instance hydration utilities for Ad4mModel.
3
- *
4
- * Both `getData()` (single-instance path) and `instancesFromSurrealResult()`
5
- * (bulk path) delegate to `hydrateInstanceFromLinks()` and
6
- * `evaluateCustomGetters()` here, guaranteeing identical semantics.
7
- *
8
- * Previously the two implementations diverged — most notably, `getData()` used
9
- * "latest-wins" for properties while `instancesFromSurrealResult()` used
10
- * "first-wins". Both now use latest-wins (last ASC-ordered link per predicate).
11
- */
12
-
13
- import { Literal } from "../../Literal";
14
- import { PerspectiveProxy } from "../../perspectives/PerspectiveProxy";
15
- import type { ModelMetadata } from "../types";
16
- import { formatSurrealValue } from "./surrealCompiler";
17
-
18
- // ─────────────────────────────────────────────────────────────────────────────
19
- // Types
20
- // ─────────────────────────────────────────────────────────────────────────────
21
-
22
- /** Raw link row as returned by SurrealDB queries. */
23
- export interface RawLink {
24
- predicate: string;
25
- target: string;
26
- author?: string;
27
- timestamp?: string | number;
28
- }
29
-
30
- // ─────────────────────────────────────────────────────────────────────────────
31
- // Helpers
32
- // ─────────────────────────────────────────────────────────────────────────────
33
-
34
- /**
35
- * Normalise a SurrealDB timestamp to epoch-milliseconds.
36
- *
37
- * - ISO strings (`"2024-01-01T00:00:00Z"`) → `Date.getTime()`
38
- * - Numeric strings (`"1700000000000"`) → `parseInt`
39
- * - Numbers → returned as-is
40
- * - Anything else → returned as-is (no data loss)
41
- */
42
- export function normalizeTimestamp(ts: any): number | string {
43
- if (typeof ts === "number") return ts;
44
- if (typeof ts === "string") {
45
- if (ts.includes("T")) {
46
- const ms = new Date(ts).getTime();
47
- return isNaN(ms) ? ts : ms;
48
- }
49
- const parsed = parseInt(ts, 10);
50
- return isNaN(parsed) ? ts : parsed;
51
- }
52
- return ts;
53
- }
54
-
55
- /**
56
- * Resolve a raw SurrealDB link target to a typed JavaScript value.
57
- *
58
- * Resolution order:
59
- * 1. Non-literal `resolveLanguage` → `perspective.getExpression(target)`
60
- * 2. `literal://` URL → `Literal.fromUrl(target).get().data`
61
- * 3. Otherwise → raw string unchanged
62
- */
63
- async function resolveValue(
64
- raw: string,
65
- resolveLanguage: string | undefined,
66
- perspective: PerspectiveProxy,
67
- propName: string,
68
- ): Promise<any> {
69
- // Non-literal language: fetch the expression via the perspective
70
- if (
71
- resolveLanguage &&
72
- resolveLanguage !== "literal" &&
73
- typeof raw === "string" &&
74
- !raw.startsWith("literal://")
75
- ) {
76
- try {
77
- const expression = await perspective.getExpression(raw);
78
- if (expression) {
79
- try {
80
- return JSON.parse(expression.data);
81
- } catch {
82
- return expression.data;
83
- }
84
- }
85
- } catch (e) {
86
- console.warn(`Failed to resolve expression for ${propName}:`, e);
87
- }
88
- return raw;
89
- }
90
-
91
- // Literal URL: parse inline — only when resolveLanguage is 'literal' or unset.
92
- // A property with a non-literal resolveLanguage whose stored target happens to
93
- // start with 'literal://' (e.g. a model baseExpression URI stored as a string
94
- // property value) must NOT be unwrapped here, or the URI itself is destroyed.
95
- // Note: unlike the old monolithic Ad4mModel.ts, ALL scalar values in our
96
- // mutation layer are stored as literal:// (when they have no URI scheme), so
97
- // resolveLanguage === undefined is the normal case for plain string/number props.
98
- if (
99
- (resolveLanguage === "literal" || resolveLanguage === undefined) &&
100
- typeof raw === "string" &&
101
- raw.startsWith("literal://")
102
- ) {
103
- try {
104
- const parsed = Literal.fromUrl(raw).get();
105
- return parsed.data !== undefined ? parsed.data : parsed;
106
- } catch {
107
- // fall through to raw
108
- }
109
- }
110
-
111
- return raw;
112
- }
113
-
114
- // ─────────────────────────────────────────────────────────────────────────────
115
- // Public API
116
- // ─────────────────────────────────────────────────────────────────────────────
117
-
118
- /**
119
- * Hydrates a model instance from a flat array of raw SurrealDB link rows.
120
- *
121
- * **Guarantees:**
122
- * - Properties use *"latest-wins"* semantics — links must be ordered
123
- * `ASC` by `timestamp`; the last matching link per predicate wins.
124
- * - Forward relations preserve insertion order (links already ASC).
125
- * - `createdAt` / `updatedAt` / `author` are derived from the global
126
- * min/max timestamps across **all** links (not just property links).
127
- *
128
- * **Does NOT handle** (left to the caller):
129
- * - Reverse relations — require a separate `WHERE out.uri = $base` query.
130
- * - Custom getter evaluation — call `evaluateCustomGetters()` afterwards.
131
- * - `relatedModel` eager hydration — do that in a batch pass afterwards.
132
- */
133
- export async function hydrateInstanceFromLinks(
134
- instance: any,
135
- links: RawLink[],
136
- metadata: ModelMetadata,
137
- perspective: PerspectiveProxy,
138
- ): Promise<void> {
139
- if (!links || links.length === 0) return;
140
-
141
- // ── Global timestamp / author tracking ─────────────────────────────────────
142
- // Normalise to epoch-ms so numeric and ISO timestamps compare correctly.
143
- let minTimestamp: number | null = null;
144
- let maxTimestamp: number | null = null;
145
- let originalAuthor: string | null = null;
146
-
147
- for (const link of links) {
148
- const ts = link.timestamp;
149
- if (ts == null) continue;
150
- const t = Number(normalizeTimestamp(ts));
151
- if (isNaN(t)) continue;
152
- if (minTimestamp === null || t < minTimestamp) {
153
- minTimestamp = t;
154
- originalAuthor = link.author ?? null;
155
- }
156
- if (maxTimestamp === null || t > maxTimestamp) {
157
- maxTimestamp = t;
158
- }
159
- }
160
-
161
- // ── Properties ──────────────────────────────────────────────────────────────
162
- // Links are ordered ASC by timestamp; the LAST match is the most recent value.
163
- for (const [propName, propMeta] of Object.entries(metadata.properties)) {
164
- if (propMeta.getter) continue; // handled separately by evaluateCustomGetters
165
-
166
- const matching = links.filter(
167
- (l) => l.predicate === propMeta.predicate && l.target !== "None",
168
- );
169
- if (matching.length === 0) continue;
170
-
171
- const link = matching[matching.length - 1]; // latest wins
172
- let value: any = await resolveValue(
173
- link.target,
174
- propMeta.resolveLanguage,
175
- perspective,
176
- propName,
177
- );
178
-
179
- if (propMeta.transform && typeof propMeta.transform === "function") {
180
- value = propMeta.transform(value);
181
- }
182
-
183
- instance[propName] = value;
184
- }
185
-
186
- // ── Forward relations ───────────────────────────────────────────────────────
187
- // Collect targets in their natural (ASC timestamp) order; filter None/empty.
188
- const forwardRelations = Object.entries(metadata.relations).filter(
189
- ([, m]) => !m.getter && m.direction !== "reverse",
190
- );
191
- for (const [relationName, relMeta] of forwardRelations) {
192
- const matching = links.filter((l) => l.predicate === relMeta.predicate);
193
- const values = matching
194
- .map((l) => l.target)
195
- .filter((v) => v !== undefined && v !== null && v !== "" && v !== "None");
196
-
197
- // maxCount === 1: take first value (oldest) — "@HasOne" has only one link
198
- // in the happy path; "first" vs "last" only differs in error/corrupt state.
199
- instance[relationName] =
200
- relMeta.maxCount === 1 ? (values[0] ?? null) : values;
201
- }
202
-
203
- // ── Author & timestamps ──────────────────────────────────────────────────────
204
- if (originalAuthor) instance.author = originalAuthor;
205
- if (minTimestamp !== null)
206
- instance.createdAt = normalizeTimestamp(minTimestamp);
207
- if (maxTimestamp !== null)
208
- instance.updatedAt = normalizeTimestamp(maxTimestamp);
209
- }
210
-
211
- /**
212
- * Evaluates custom SurrealQL getter expressions for all `getter`-decorated
213
- * properties and relations on a single model instance.
214
- *
215
- * Called by both `getData()` (single-instance path) and
216
- * `instancesFromSurrealResult()` (bulk path) — single implementation so
217
- * neither path can diverge.
218
- */
219
- export async function evaluateCustomGetters(
220
- instance: any,
221
- perspective: PerspectiveProxy,
222
- metadata: ModelMetadata,
223
- ): Promise<void> {
224
- const safeBase = formatSurrealValue(instance.id);
225
-
226
- // Property getters
227
- for (const [propName, propMeta] of Object.entries(metadata.properties)) {
228
- if (!propMeta.getter) continue;
229
- try {
230
- const query = propMeta.getter.replace(/Base/g, safeBase);
231
- const result = await perspective.querySurrealDB(
232
- `SELECT (${query}) AS value FROM node WHERE uri = ${safeBase}`,
233
- );
234
- if (
235
- result?.length > 0 &&
236
- result[0].value !== undefined &&
237
- result[0].value !== null &&
238
- result[0].value !== "None" &&
239
- result[0].value !== ""
240
- ) {
241
- instance[propName] = result[0].value;
242
- }
243
- } catch (error) {
244
- console.warn(`Failed to evaluate getter for ${propName}:`, error);
245
- }
246
- }
247
-
248
- // Relation getters
249
- for (const [relationName, relMeta] of Object.entries(metadata.relations)) {
250
- if (!relMeta.getter) continue;
251
- try {
252
- const query = relMeta.getter.replace(/Base/g, safeBase);
253
- const result = await perspective.querySurrealDB(
254
- `SELECT (${query}) AS value FROM node WHERE uri = ${safeBase}`,
255
- );
256
- if (
257
- result?.length > 0 &&
258
- result[0].value !== undefined &&
259
- result[0].value !== null
260
- ) {
261
- const value = result[0].value;
262
- instance[relationName] = Array.isArray(value)
263
- ? value.filter(
264
- (v: any) =>
265
- v !== undefined && v !== null && v !== "" && v !== "None",
266
- )
267
- : value;
268
- }
269
- } catch (error) {
270
- console.warn(`Failed to evaluate getter for ${relationName}:`, error);
271
- }
272
- }
273
- }