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

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 +6893 -5884
  3. package/lib/index.js +6889 -5872
  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 +3760 -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 +4386 -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,510 +0,0 @@
1
- /**
2
- * Static query operations for Ad4mModel.
3
- *
4
- * Extracted from Ad4mModel.ts (Phase 3a Part 3). Every function here is a
5
- * pure-static helper that takes a model constructor (`ctor`) as its first
6
- * argument instead of relying on `this`. Ad4mModel wraps each one with a
7
- * thin static method so the public API is completely unchanged.
8
- *
9
- * The `Ad4mModelCtor<T>` type is imported (type-only) from QueryBuilder so
10
- * there is no runtime circular dependency.
11
- */
12
-
13
- import type { PerspectiveProxy } from "../../perspectives/PerspectiveProxy";
14
- import type {
15
- Query,
16
- Where,
17
- ResultsWithTotalCount,
18
- PaginationResult,
19
- } from "../types";
20
- import type { Ad4mModelCtor } from "./ModelQueryBuilder";
21
- import {
22
- buildSurrealQuery,
23
- buildSurrealCountQuery,
24
- matchesCondition,
25
- } from "./surrealCompiler";
26
- import { hydrateInstanceFromLinks, evaluateCustomGetters } from "./hydration";
27
- import { captureSnapshot } from "./snapshot";
28
- import { escapeSurrealString } from "../../utils";
29
- import { normalizeParentQuery } from "../parentUtils";
30
-
31
- // ─────────────────────────────────────────────────────────────────────────────
32
- // Query-to-SurrealQL helpers
33
- // ─────────────────────────────────────────────────────────────────────────────
34
-
35
- /**
36
- * Translates a high-level {@link Query} object to a SurrealQL string.
37
- *
38
- * @param ctor - The Ad4mModel subclass (provides getModelMetadata)
39
- * @param perspective - Not used for query building but kept for API symmetry
40
- * @param query - High-level query parameters
41
- */
42
- export async function queryToSurrealQL(
43
- ctor: Ad4mModelCtor<any>,
44
- _perspective: PerspectiveProxy,
45
- query: Query,
46
- ): Promise<string> {
47
- const normalizedQuery = query.parent
48
- ? { ...query, parent: normalizeParentQuery(query.parent, ctor as any) }
49
- : query;
50
- return buildSurrealQuery((ctor as any).getModelMetadata(), normalizedQuery);
51
- }
52
-
53
- /**
54
- * Translates a high-level {@link Query} object to a SurrealQL COUNT string.
55
- */
56
- export async function countQueryToSurrealQL(
57
- ctor: Ad4mModelCtor<any>,
58
- _perspective: PerspectiveProxy,
59
- query: Query,
60
- ): Promise<string> {
61
- const normalizedQuery = query.parent
62
- ? { ...query, parent: normalizeParentQuery(query.parent, ctor as any) }
63
- : query;
64
- return buildSurrealCountQuery((ctor as any).getModelMetadata(), normalizedQuery);
65
- }
66
-
67
- // ─────────────────────────────────────────────────────────────────────────────
68
- // instancesFromSurrealResult — the core hydration/assembly pipeline
69
- // ─────────────────────────────────────────────────────────────────────────────
70
-
71
- /**
72
- * Converts raw SurrealDB result rows to hydrated Ad4mModel instances.
73
- *
74
- * This is the single-pass pipeline that:
75
- * 1. Creates a model instance for each `source_uri` row
76
- * 2. Hydrates properties, forward relations, author and timestamps
77
- * 3. Fetches reverse-relation links in one batch query
78
- * 4. Batch-hydrates nested `relatedModel` relations (no N+1)
79
- * 5. Evaluates custom SurrealQL getters
80
- * 6. Post-filters and sorts in JS for operators that SurrealDB can't handle
81
- * 7. Applies offset/limit pagination
82
- *
83
- * @internal
84
- */
85
- export async function instancesFromSurrealResult<T>(
86
- ctor: Ad4mModelCtor<T>,
87
- perspective: PerspectiveProxy,
88
- query: Query,
89
- result: any[],
90
- _hydrateRelations = true,
91
- ): Promise<ResultsWithTotalCount<T>> {
92
- if (!result || result.length === 0) return { results: [], totalCount: 0 };
93
-
94
- const metadata = (ctor as any).getModelMetadata();
95
- const requestedProperties = query?.properties || [];
96
-
97
- // ── 0. Pre-validate the `properties` option ───────────────────────────────
98
- //
99
- // An empty array is disallowed: it almost certainly indicates a bug in the
100
- // caller (a computed list that produced no entries). Pass `undefined` or
101
- // omit the field entirely to get all properties.
102
- //
103
- // This check is BEFORE the row loop so the error propagates to the caller
104
- // instead of being swallowed by the per-row try/catch.
105
- if (query?.properties !== undefined && requestedProperties.length === 0) {
106
- throw new Error(
107
- "Ad4mModel: properties[] must not be empty. Omit the field to retrieve all properties.",
108
- );
109
- }
110
-
111
- // ── 1. Build instances from rows ──────────────────────────────────────────────────
112
- const instances: T[] = [];
113
- for (const row of result) {
114
- try {
115
- const base = row.source_uri;
116
- if (!base) continue;
117
-
118
- const links: any[] = row.links || [];
119
- const instance = new ctor(perspective, base) as any;
120
-
121
- // Shared hydration: properties + forward relations + author + timestamps
122
- await hydrateInstanceFromLinks(instance, links, metadata, perspective);
123
-
124
- // If the query asked for specific properties only, strip schema-declared
125
- // fields that weren't requested. We only touch fields that are declared in
126
- // the schema (via @Property / relation decorators) plus the well-known
127
- // metadata fields (author, createdAt, updatedAt). Internal machinery such
128
- // as _id, _perspective, _savedOnce, and the dynamically-wired addX /
129
- // removeX / setX methods must never be deleted — they are not enumerated
130
- // by their public names in Object.keys, but _id and _perspective ARE plain
131
- // own properties and would be wrongly removed by a naïve Object.keys scan.
132
- //
133
- // Note: `id` is always accessible regardless — it is a prototype getter
134
- // backed by the private _id field and cannot be deleted from an instance.
135
- if (requestedProperties.length > 0) {
136
- const schemaKeys = [
137
- ...Object.keys(metadata.properties),
138
- ...Object.keys(metadata.relations),
139
- "author",
140
- "createdAt",
141
- "updatedAt",
142
- ];
143
- for (const key of schemaKeys) {
144
- if (!requestedProperties.includes(key)) {
145
- // Don't delete relation keys that are listed in the include map.
146
- // The include-hydration step (step 3 below) needs the raw IDs to
147
- // batch-fetch related models, and the hydrated result should appear
148
- // in the final output even when the relation is not in `properties`.
149
- if (query?.include && key in query.include) continue;
150
- delete instance[key];
151
- }
152
- }
153
- }
154
-
155
- instances.push(instance);
156
- } catch (error) {
157
- console.error(
158
- `Failed to process SurrealDB instance ${(error as any)?.base ?? "unknown"}:`,
159
- error,
160
- );
161
- }
162
- }
163
-
164
- // ── 2. Reverse relations (one batch query for all instances) ──────────────
165
- // Forward links (->link) are in row.links; reverse links (<-link) are not.
166
- const reverseRelationEntries = Object.entries(metadata.relations).filter(
167
- ([, m]: [string, any]) => !m.getter && m.direction === "reverse",
168
- );
169
- if (reverseRelationEntries.length > 0 && instances.length > 0) {
170
- try {
171
- const inList = instances
172
- .map((i: any) => `'${escapeSurrealString(i.id)}'`)
173
- .join(", ");
174
- const reverseLinksQuery = `
175
- SELECT in.uri AS source, predicate, out.uri AS target, author, timestamp
176
- FROM link
177
- WHERE out.uri IN [${inList}]
178
- ORDER BY timestamp ASC
179
- `;
180
- const reverseLinks: any[] =
181
- (await perspective.querySurrealDB(reverseLinksQuery)) ?? [];
182
-
183
- for (const instance of instances) {
184
- for (const [relationName, relationMeta] of reverseRelationEntries) {
185
- const matching = reverseLinks.filter(
186
- (l: any) =>
187
- l.target === (instance as any).id &&
188
- l.predicate === (relationMeta as any).predicate,
189
- );
190
- const values = matching.map((l: any) => l.source);
191
- (instance as any)[relationName] =
192
- (relationMeta as any).maxCount === 1 ? (values[0] ?? null) : values;
193
- }
194
- }
195
- } catch (e) {
196
- console.warn("Failed to fetch reverse links for instances:", e);
197
- }
198
- }
199
-
200
- // ── 3. Batch-hydrate relations via explicit `include` map ─────────────────
201
- //
202
- // No hydration is performed unless `query.include` is set.
203
- // Each key in the map is a relation field name; the value is either `true`
204
- // (hydrate all with no filter) or a Query to filter/order/limit the nested set.
205
- if (_hydrateRelations && query?.include) {
206
- const includeMap = query.include;
207
- const hydrateEntries = Object.entries(metadata.relations).filter(
208
- ([name, m]: [string, any]) =>
209
- !m.getter && name in includeMap && !!m.relatedModel,
210
- );
211
- for (const [relationName, relationMeta] of hydrateEntries) {
212
- const allIds = Array.from(
213
- new Set(
214
- instances.flatMap((i: any) => {
215
- const val = i[relationName];
216
- if (!val) return [];
217
- return Array.isArray(val) ? val.filter(Boolean) : [val];
218
- }),
219
- ),
220
- ) as string[];
221
- if (allIds.length === 0) continue;
222
- try {
223
- // Resolve the model class from the relatedModel factory.
224
- const RelatedModel = (relationMeta as any).relatedModel();
225
- // Merge caller's sub-query with the id pre-filter.
226
- const entry = includeMap[relationName];
227
- const subQuery: Query =
228
- entry === true
229
- ? { where: { id: allIds } }
230
- : { ...entry, where: { id: allIds, ...(entry as Query).where } };
231
- // Pass _hydrateRelations=true when the sub-entry itself carries an
232
- // include map (nested eager loading); otherwise false to stop recursion.
233
- const nestedHydrate = entry !== true && !!(entry as Query).include;
234
- const allHydrated = await _findAllInternal(
235
- RelatedModel,
236
- perspective,
237
- subQuery,
238
- nestedHydrate,
239
- );
240
- const hydratedMap = new Map<string, any>(
241
- allHydrated.map((h: any) => [h.id, h]),
242
- );
243
- // When the sub-query specifies an `order`, the sorted order from
244
- // _findAllInternal must be preserved. We filter allHydrated (which is
245
- // already sorted) by IDs belonging to this instance, rather than
246
- // iterating `val` (which is in the original link-insertion order).
247
- const hasSubOrder = entry !== true && !!(entry as Query).order;
248
- for (const instance of instances) {
249
- const val = (instance as any)[relationName];
250
- if (!val) continue;
251
- if (Array.isArray(val)) {
252
- if (hasSubOrder) {
253
- const valSet = new Set(val as string[]);
254
- (instance as any)[relationName] = allHydrated.filter((h: any) =>
255
- valSet.has(h.id),
256
- );
257
- } else {
258
- (instance as any)[relationName] = val
259
- .map((id: string) => hydratedMap.get(id))
260
- .filter((h: any) => h !== undefined);
261
- }
262
- } else if (typeof val === "string") {
263
- (instance as any)[relationName] = hydratedMap.get(val) ?? null;
264
- }
265
- }
266
- } catch (e) {
267
- console.warn(`Failed to batch-hydrate ${relationName}:`, e);
268
- }
269
- }
270
- }
271
-
272
- // ── 4. Custom SurrealQL getters (single pass, all instances) ─────────────
273
- for (const instance of instances) {
274
- await evaluateCustomGetters(instance as any, perspective, metadata);
275
- }
276
-
277
- // ── 5. Snapshot capture — baseline for dirty tracking on next save() ──────
278
- const schemaKeys = [
279
- ...Object.keys(metadata.properties),
280
- ...Object.keys(metadata.relations),
281
- ];
282
- for (const instance of instances) {
283
- captureSnapshot(instance as object, schemaKeys);
284
- }
285
-
286
- // ── 6. Post-filter: where conditions that SurrealDB can't handle in SQL ───
287
- // • author / timestamp (computed from grouped links)
288
- // • Comparison operators: gt, gte, lt, lte, between, contains
289
- let filteredInstances = instances;
290
- if (query.where) {
291
- filteredInstances = instances.filter((instance) => {
292
- for (const [propertyName, condition] of Object.entries(query.where!)) {
293
- // base/id filtering is already done in SQL
294
- if (propertyName === "base" || propertyName === "id") continue;
295
-
296
- // author and timestamp: always filter in JS
297
- if (propertyName === "author" || propertyName === "timestamp") {
298
- if (!matchesCondition((instance as any)[propertyName], condition)) {
299
- return false;
300
- }
301
- continue;
302
- }
303
-
304
- // Comparison operators: only these need JS post-filtering
305
- if (
306
- typeof condition === "object" &&
307
- condition !== null &&
308
- !Array.isArray(condition)
309
- ) {
310
- const cond = condition as any;
311
- const hasComparisonOps =
312
- cond.gt !== undefined ||
313
- cond.gte !== undefined ||
314
- cond.lt !== undefined ||
315
- cond.lte !== undefined ||
316
- cond.between !== undefined ||
317
- cond.contains !== undefined;
318
- if (hasComparisonOps) {
319
- if (!matchesCondition((instance as any)[propertyName], condition)) {
320
- return false;
321
- }
322
- }
323
- }
324
- }
325
- return true;
326
- });
327
- }
328
-
329
- // ── 7. Sort in JavaScript ─────────────────────────────────────────────────
330
- // If limit/offset is used but no explicit order, default to timestamp ASC
331
- // to guarantee consistent pagination behaviour.
332
- const effectiveOrder =
333
- query.order ||
334
- (query.limit !== undefined || query.offset !== undefined
335
- ? { timestamp: "ASC" as "ASC" }
336
- : null);
337
-
338
- if (effectiveOrder) {
339
- const orderEntries = Object.entries(effectiveOrder) as [
340
- string,
341
- "ASC" | "DESC",
342
- ][];
343
- filteredInstances.sort((a: any, b: any) => {
344
- for (const [orderPropName, orderDirection] of orderEntries) {
345
- let aVal = a[orderPropName];
346
- let bVal = b[orderPropName];
347
- if (aVal === undefined && bVal === undefined) continue;
348
- if (aVal === undefined) return orderDirection === "ASC" ? 1 : -1;
349
- if (bVal === undefined) return orderDirection === "ASC" ? -1 : 1;
350
- let comparison = 0;
351
- if (typeof aVal === "number" && typeof bVal === "number") {
352
- comparison = aVal - bVal;
353
- } else if (typeof aVal === "string" && typeof bVal === "string") {
354
- comparison = aVal.localeCompare(bVal);
355
- } else {
356
- comparison = String(aVal).localeCompare(String(bVal));
357
- }
358
- if (comparison !== 0)
359
- return orderDirection === "DESC" ? -comparison : comparison;
360
- }
361
- return 0;
362
- });
363
- }
364
-
365
- // ── 8. Calculate totalCount BEFORE limit/offset, then paginate ────────────
366
- const totalCount = filteredInstances.length;
367
- let paginatedInstances = filteredInstances;
368
- if (query.offset !== undefined || query.limit !== undefined) {
369
- const start = query.offset || 0;
370
- const end = query.limit ? start + query.limit : undefined;
371
- paginatedInstances = filteredInstances.slice(start, end);
372
- }
373
-
374
- return { results: paginatedInstances, totalCount };
375
- }
376
-
377
- // ─────────────────────────────────────────────────────────────────────────────
378
- // High-level find/count operations
379
- // ─────────────────────────────────────────────────────────────────────────────
380
-
381
- /**
382
- * Internal findAll used by the public static and by eager-hydration depth-guards.
383
- * Pass `_hydrateRelations = false` to prevent recursive nested-model hydration.
384
- */
385
- export async function _findAllInternal<T>(
386
- ctor: Ad4mModelCtor<T>,
387
- perspective: PerspectiveProxy,
388
- query: Query = {},
389
- _hydrateRelations = true,
390
- ): Promise<T[]> {
391
- const surrealQuery = await queryToSurrealQL(ctor, perspective, query);
392
- const result = await perspective.querySurrealDB(surrealQuery);
393
- const { results } = await instancesFromSurrealResult(
394
- ctor,
395
- perspective,
396
- query,
397
- result,
398
- _hydrateRelations,
399
- );
400
- return results;
401
- }
402
-
403
- /** Returns all matching instances. */
404
- export async function findAll<T>(
405
- ctor: Ad4mModelCtor<T>,
406
- perspective: PerspectiveProxy,
407
- query: Query,
408
- ): Promise<T[]> {
409
- return _findAllInternal(ctor, perspective, query, true);
410
- }
411
-
412
- /** Returns the first matching instance, or `null` if none found. */
413
- export async function findOne<T>(
414
- ctor: Ad4mModelCtor<T>,
415
- perspective: PerspectiveProxy,
416
- query: Query,
417
- ): Promise<T | null> {
418
- const results = await findAll(ctor, perspective, { ...query, limit: 1 });
419
- return results[0] ?? null;
420
- }
421
-
422
- /** Returns all matching instances together with the total unfilterd count. */
423
- export async function findAllAndCount<T>(
424
- ctor: Ad4mModelCtor<T>,
425
- perspective: PerspectiveProxy,
426
- query: Query,
427
- ): Promise<ResultsWithTotalCount<T>> {
428
- const surrealQuery = await queryToSurrealQL(ctor, perspective, query);
429
- const result = await perspective.querySurrealDB(surrealQuery);
430
- return instancesFromSurrealResult(ctor, perspective, query, result);
431
- }
432
-
433
- /**
434
- * Paginates results given an explicit page size and 1-based page number.
435
- * Returns metadata needed to render pagination controls.
436
- */
437
- export async function paginate<T>(
438
- ctor: Ad4mModelCtor<T>,
439
- perspective: PerspectiveProxy,
440
- pageSize: number,
441
- pageNumber: number,
442
- query: Query,
443
- ): Promise<PaginationResult<T>> {
444
- const paginationQuery: Query = {
445
- ...query,
446
- limit: pageSize,
447
- offset: pageSize * (pageNumber - 1),
448
- count: true,
449
- };
450
- const surrealQuery = await queryToSurrealQL(
451
- ctor,
452
- perspective,
453
- paginationQuery,
454
- );
455
- const result = await perspective.querySurrealDB(surrealQuery);
456
- const { results, totalCount } = await instancesFromSurrealResult(
457
- ctor,
458
- perspective,
459
- paginationQuery,
460
- result,
461
- );
462
- return { results, totalCount, pageSize, pageNumber };
463
- }
464
-
465
- /** Returns true when `where` has conditions that require JS post-filtering. */
466
- function hasJsFilterConditions(where?: Where): boolean {
467
- if (!where) return false;
468
- return Object.entries(where).some(([k, v]) => {
469
- if (k === "author" || k === "timestamp") return true;
470
- if (typeof v === "object" && v !== null && !Array.isArray(v)) {
471
- const ops = v as any;
472
- return (
473
- ops.gt !== undefined ||
474
- ops.gte !== undefined ||
475
- ops.lt !== undefined ||
476
- ops.lte !== undefined ||
477
- ops.between !== undefined ||
478
- ops.contains !== undefined
479
- );
480
- }
481
- return false;
482
- });
483
- }
484
-
485
- /** Returns a count of all matching instances. */
486
- export async function count(
487
- ctor: Ad4mModelCtor<any>,
488
- perspective: PerspectiveProxy,
489
- query: Query,
490
- ): Promise<number> {
491
- // Strip pagination — count always wants total, not the paginated slice.
492
- const countQuery: Query = { ...query, limit: undefined, offset: undefined };
493
- const surrealQuery = await countQueryToSurrealQL(
494
- ctor,
495
- perspective,
496
- countQuery,
497
- );
498
- const result = await perspective.querySurrealDB(surrealQuery);
499
- if (!result || result.length === 0) return 0;
500
- // Fast path: SQL WHERE handles all conditions — skip full instance hydration.
501
- if (!hasJsFilterConditions(countQuery.where)) return result.length;
502
- // Slow path: hydrate so JS post-filters (gt/gte/author/etc.) can run.
503
- const { totalCount } = await instancesFromSurrealResult(
504
- ctor,
505
- perspective,
506
- countQuery,
507
- result,
508
- );
509
- return totalCount ?? 0;
510
- }
@@ -1,126 +0,0 @@
1
- /**
2
- * Dirty-tracking snapshot registry for Ad4mModel instances.
3
- *
4
- * A lightweight WeakMap-based store that records the schema-declared field
5
- * values of an instance immediately after hydration or save. `innerUpdate`
6
- * consults this snapshot to skip writing fields that haven't changed since the
7
- * last successful persist, preventing the "re-save duplicates relations" bug.
8
- *
9
- * ## Design notes
10
- *
11
- * - A **WeakMap** is used so snapshot entries are GC'd when the instance is
12
- * collected — no manual cleanup needed.
13
- * - Arrays are normalised to `string[]` on capture (model instances → their ID
14
- * URI) so the comparison is stable regardless of whether `include` hydration
15
- * was used.
16
- * - There is **no snapshot** for a freshly constructed instance that has never
17
- * been hydrated or saved. `isDirty` returns `true` in that case, preserving
18
- * existing create-path behaviour (write everything).
19
- * - Only Tier-1 saves (no caller-provided `batchId`) trigger a post-save
20
- * rehydration via `fetchInstanceData`, which re-captures the snapshot. Tier-2
21
- * / Tier-3 (caller-managed batch / `transaction()`) skip rehydration by
22
- * design; fields that were not changed may be re-sent on the next Tier-1
23
- * save, which is idempotent and acceptable.
24
- */
25
-
26
- // ─────────────────────────────────────────────────────────────────────────────
27
- // Types
28
- // ─────────────────────────────────────────────────────────────────────────────
29
-
30
- type SnapshotEntry = Record<string, any>;
31
-
32
- // ─────────────────────────────────────────────────────────────────────────────
33
- // Registry
34
- // ─────────────────────────────────────────────────────────────────────────────
35
-
36
- const snapshots = new WeakMap<object, SnapshotEntry>();
37
-
38
- // ─────────────────────────────────────────────────────────────────────────────
39
- // Helpers
40
- // ─────────────────────────────────────────────────────────────────────────────
41
-
42
- /**
43
- * Normalise a field value for snapshot storage and comparison.
44
- *
45
- * - Arrays whose items may be model instances (from `include` hydration) are
46
- * reduced to their `id` URI strings so comparisons are stable.
47
- * - All other values are stored as-is.
48
- */
49
- function normalizeValue(value: any): any {
50
- if (Array.isArray(value)) {
51
- return value.map((v) =>
52
- v && typeof v === "object" && typeof v.id === "string" ? v.id : v,
53
- );
54
- }
55
- return value;
56
- }
57
-
58
- // ─────────────────────────────────────────────────────────────────────────────
59
- // Public API
60
- // ─────────────────────────────────────────────────────────────────────────────
61
-
62
- /**
63
- * Records the current schema-field values of `instance` as its clean baseline.
64
- *
65
- * Call this after every hydration (bulk or single-instance path) and after
66
- * every successful internal-batch save (the latter comes for free because
67
- * `saveInstance` calls `fetchInstanceData` which ends with a `captureSnapshot`
68
- * call).
69
- *
70
- * @param instance - The Ad4mModel instance to snapshot.
71
- * @param keys - Schema-declared field names to record (@Property keys +
72
- * relation keys). Internal machinery (`_id`, `_perspective`,
73
- * dynamically-wired `addX`/`removeX`/`setX` methods) must
74
- * NOT be included.
75
- */
76
- export function captureSnapshot(instance: object, keys: string[]): void {
77
- const entry: SnapshotEntry = {};
78
- for (const key of keys) {
79
- entry[key] = normalizeValue((instance as any)[key]);
80
- }
81
- snapshots.set(instance, entry);
82
- }
83
-
84
- /**
85
- * Returns the snapshot entry for `instance`, or `undefined` if none has been
86
- * captured yet (i.e. the instance has never been hydrated or saved via an
87
- * internal batch).
88
- */
89
- export function readSnapshot(instance: object): SnapshotEntry | undefined {
90
- return snapshots.get(instance);
91
- }
92
-
93
- /**
94
- * Returns `true` if `currentValue` differs from the snapshot value for `key`.
95
- *
96
- * Always returns `true` (→ write the field) when:
97
- * - No snapshot has been captured (create path / instance never hydrated).
98
- * - The key was not present in the snapshot (new field added after hydration).
99
- *
100
- * Array comparison is order-insensitive: both sides are sorted before checking
101
- * element-wise equality, because a fresh hydration may return relation IDs in a
102
- * different order than they were originally written.
103
- */
104
- export function isDirty(
105
- instance: object,
106
- key: string,
107
- currentValue: any,
108
- ): boolean {
109
- const snap = snapshots.get(instance);
110
- if (!snap) return true; // no snapshot → always write (create path)
111
- if (!(key in snap)) return true; // field absent from snapshot → write
112
-
113
- const snapVal = snap[key];
114
- const currNorm = normalizeValue(currentValue);
115
-
116
- if (Array.isArray(currNorm) && Array.isArray(snapVal)) {
117
- if (currNorm.length !== snapVal.length) return true;
118
- // Relations are semantically sets; sort before comparing so reordering
119
- // after a fresh hydration doesn't produce false positives.
120
- const a = [...currNorm].sort();
121
- const b = [...snapVal].sort();
122
- return a.some((v, i) => v !== b[i]);
123
- }
124
-
125
- return currNorm !== snapVal;
126
- }