@coasys/ad4m 0.12.0-rc1-dev.1 → 0.12.0-rc1-dev.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.
- package/jest.config.js +4 -4
- package/lib/index.cjs +5999 -6046
- package/lib/index.js +5977 -6040
- package/lib/src/Ad4mClient.d.ts +16 -9
- package/lib/src/Ad4mClient.js +25 -46
- package/lib/src/Ad4mClient.test.d.ts +1 -0
- package/lib/src/Ad4mClient.test.js +1204 -0
- package/lib/src/Literal.d.ts +2 -1
- package/lib/src/Literal.js +35 -38
- package/lib/src/Literal.test.d.ts +1 -0
- package/lib/src/Literal.test.js +41 -0
- package/lib/src/SmartLiteral.d.ts +2 -1
- package/lib/src/SmartLiteral.js +15 -30
- package/lib/src/agent/AgentClient.d.ts +4 -1
- package/lib/src/agent/AgentClient.js +99 -79
- package/lib/src/ai/AIClient.d.ts +2 -1
- package/lib/src/ai/AIClient.js +220 -224
- package/lib/src/expression/ExpressionClient.d.ts +1 -1
- package/lib/src/expression/ExpressionClient.js +86 -73
- package/lib/src/index.d.ts +1 -1
- package/lib/src/index.js +1 -1
- package/lib/src/language/LanguageClient.d.ts +1 -1
- package/lib/src/language/LanguageClient.js +52 -52
- package/lib/src/model/Ad4mModel.d.ts +157 -937
- package/lib/src/model/Ad4mModel.js +212 -2799
- package/lib/src/model/Ad4mModel.test.js +1002 -561
- package/lib/src/model/decorators.d.ts +94 -426
- package/lib/src/model/decorators.js +333 -741
- package/lib/src/model/mutation.d.ts +81 -0
- package/lib/src/model/mutation.js +317 -0
- package/lib/src/model/parentUtils.d.ts +32 -0
- package/lib/src/model/parentUtils.js +64 -0
- package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
- package/lib/src/model/prolog/generatePrologFacts.js +139 -0
- package/lib/src/model/prolog/index.d.ts +1 -0
- package/lib/src/model/prolog/index.js +1 -0
- package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
- package/lib/src/model/query/ModelQueryBuilder.js +115 -0
- package/lib/src/model/query/QueryBuilder.d.ts +101 -0
- package/lib/src/model/query/QueryBuilder.js +193 -0
- package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
- package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
- package/lib/src/model/query/fetchInstance.d.ts +24 -0
- package/lib/src/model/query/fetchInstance.js +144 -0
- package/lib/src/model/query/hydration.d.ts +54 -0
- package/lib/src/model/query/hydration.js +214 -0
- package/lib/src/model/query/operations.d.ts +59 -0
- package/lib/src/model/query/operations.js +384 -0
- package/lib/src/model/query/snapshot.d.ts +59 -0
- package/lib/src/model/query/snapshot.js +106 -0
- package/lib/src/model/query/surrealCompiler.d.ts +42 -0
- package/lib/src/model/query/surrealCompiler.js +304 -0
- package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
- package/lib/src/model/schema/fromJSONSchema.js +264 -0
- package/lib/src/model/schema/metadata.d.ts +15 -0
- package/lib/src/model/schema/metadata.js +112 -0
- package/lib/src/model/subscription.d.ts +47 -0
- package/lib/src/model/subscription.js +231 -0
- package/lib/src/model/transaction.d.ts +27 -0
- package/lib/src/model/transaction.js +32 -0
- package/lib/src/model/types.d.ts +195 -0
- package/lib/src/model/types.js +8 -0
- package/lib/src/model/util.js +7 -7
- package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +5 -1
- package/lib/src/neighbourhood/NeighbourhoodClient.js +263 -181
- package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -1
- package/lib/src/neighbourhood/NeighbourhoodProxy.js +13 -28
- package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +1 -5
- package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
- package/lib/src/perspectives/PerspectiveClient.js +316 -240
- package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -92
- package/lib/src/perspectives/PerspectiveProxy.js +803 -444
- package/lib/src/runtime/RuntimeClient.d.ts +5 -1
- package/lib/src/runtime/RuntimeClient.js +412 -238
- package/lib/src/shacl/SHACLFlow.test.js +164 -105
- package/lib/src/shacl/SHACLShape.d.ts +17 -3
- package/lib/src/shacl/SHACLShape.js +127 -90
- package/lib/src/shacl/SHACLShape.test.js +244 -176
- package/lib/src/utils.d.ts +8 -0
- package/lib/src/utils.js +21 -7
- package/package.json +8 -13
- package/src/Ad4mClient.test.ts +1564 -1315
- package/src/Ad4mClient.ts +55 -54
- package/src/Literal.test.ts +45 -26
- package/src/Literal.ts +82 -66
- package/src/SmartLiteral.ts +74 -58
- package/src/agent/AgentClient.ts +144 -99
- package/src/ai/AIClient.ts +409 -359
- package/src/expression/ExpressionClient.ts +142 -96
- package/src/index.ts +1 -1
- package/src/language/LanguageClient.ts +137 -113
- package/src/model/Ad4mModel.test.ts +1128 -647
- package/src/model/Ad4mModel.ts +485 -3249
- package/src/model/IMPROVEMENTS.md +482 -0
- package/src/model/PREDICATE_COLLISION_FIX.md +651 -0
- package/src/model/README.md +317 -0
- package/src/model/SHACL_MUTATION_DECOUPLING.md +356 -0
- package/src/model/SUBSCRIPTION_STRATEGY.md +317 -0
- package/src/model/TC39_STAGE_3_DECORATORS.md +609 -0
- package/src/model/decorators.ts +689 -1046
- package/src/model/mutation.ts +461 -0
- package/src/model/parentUtils.ts +91 -0
- package/src/model/prolog/generatePrologFacts.ts +176 -0
- package/src/model/prolog/index.ts +1 -0
- package/src/model/query/ModelQueryBuilder.ts +173 -0
- package/src/model/query/fetchInstance.ts +181 -0
- package/src/model/query/hydration.ts +273 -0
- package/src/model/query/operations.ts +510 -0
- package/src/model/query/snapshot.ts +126 -0
- package/src/model/query/surrealCompiler.ts +376 -0
- package/src/model/schema/fromJSONSchema.ts +411 -0
- package/src/model/schema/metadata.ts +148 -0
- package/src/model/subscription.ts +307 -0
- package/src/model/transaction.ts +60 -0
- package/src/model/types.ts +207 -0
- package/src/model/util.ts +47 -48
- package/src/neighbourhood/NeighbourhoodClient.ts +393 -251
- package/src/neighbourhood/NeighbourhoodProxy.test.ts +3 -7
- package/src/neighbourhood/NeighbourhoodProxy.ts +58 -40
- package/src/perspectives/PerspectiveClient.ts +779 -540
- package/src/perspectives/PerspectiveProxy.ts +2860 -2053
- package/src/runtime/RuntimeClient.ts +775 -476
- package/src/shacl/SHACLFlow.test.ts +196 -129
- package/src/shacl/SHACLShape.test.ts +284 -190
- package/src/shacl/SHACLShape.ts +225 -172
- package/src/utils.ts +31 -17
- package/tsconfig.json +9 -10
- package/src/model/Subject.ts +0 -159
|
@@ -0,0 +1,510 @@
|
|
|
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
|
+
}
|
|
@@ -0,0 +1,126 @@
|
|
|
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
|
+
}
|