@coasys/ad4m 0.12.0-rc1-dev.1 → 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.
- package/jest.config.js +8 -1
- package/lib/index.cjs +13793 -12854
- package/lib/index.js +13782 -12851
- package/lib/src/Ad4mClient.test.d.ts +1 -0
- package/lib/src/Ad4mClient.test.js +1204 -0
- package/lib/src/Literal.test.d.ts +1 -0
- package/lib/src/Literal.test.js +41 -0
- package/lib/src/model/Ad4mModel.d.ts +528 -101
- package/lib/src/model/Ad4mModel.js +1670 -748
- package/lib/src/model/Ad4mModel.test.js +140 -156
- package/lib/src/model/Subject.d.ts +3 -3
- package/lib/src/model/Subject.js +25 -25
- package/lib/src/model/decorators.d.ts +259 -247
- package/lib/src/model/decorators.js +379 -422
- 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.d.ts +6 -6
- package/lib/src/model/util.js +22 -22
- package/lib/src/neighbourhood/NeighbourhoodClient.js +31 -12
- package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -9
- package/lib/src/perspectives/PerspectiveProxy.js +63 -51
- package/lib/src/shacl/SHACLShape.d.ts +9 -0
- package/lib/src/shacl/SHACLShape.js +28 -4
- package/lib/src/shims/reflect-metadata.d.ts +0 -0
- package/lib/src/shims/type-graphql.d.ts +32 -0
- package/lib/src/src/Ad4mClient.d.ts +28 -0
- package/lib/src/src/Address.d.ts +1 -0
- package/lib/src/src/DID.d.ts +1 -0
- package/lib/src/src/Exception.d.ts +7 -0
- package/lib/src/src/Literal.d.ts +7 -0
- package/lib/src/src/PubSub.d.ts +17 -0
- package/lib/src/src/SmartLiteral.d.ts +12 -0
- package/lib/src/src/agent/Agent.d.ts +110 -0
- package/lib/src/src/agent/AgentClient.d.ts +62 -0
- package/lib/src/src/agent/AgentResolver.d.ts +30 -0
- package/lib/src/src/agent/AgentStatus.d.ts +8 -0
- package/lib/src/src/ai/AIClient.d.ts +32 -0
- package/lib/src/src/ai/AIResolver.d.ts +75 -0
- package/lib/src/src/ai/Tasks.d.ts +37 -0
- package/lib/src/src/buildSchema.d.ts +1 -0
- package/lib/src/src/expression/Expression.d.ts +28 -0
- package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
- package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
- package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
- package/lib/src/src/index.d.ts +35 -0
- package/lib/src/src/jestSetup.d.ts +1 -0
- package/lib/src/src/language/Icon.d.ts +4 -0
- package/lib/src/src/language/Language.d.ts +206 -0
- package/lib/src/src/language/LanguageClient.d.ts +17 -0
- package/lib/src/src/language/LanguageContext.d.ts +37 -0
- package/lib/src/src/language/LanguageHandle.d.ts +9 -0
- package/lib/src/src/language/LanguageMeta.d.ts +35 -0
- package/lib/src/src/language/LanguageRef.d.ts +6 -0
- package/lib/src/src/language/LanguageResolver.d.ts +19 -0
- package/lib/src/src/links/Links.d.ts +39 -0
- package/lib/src/src/links/Links.test.d.ts +1 -0
- package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
- package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
- package/lib/src/src/model/Subject.d.ts +25 -0
- package/lib/src/src/model/decorators.d.ts +545 -0
- package/lib/src/src/model/util.d.ts +12 -0
- package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
- package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
- package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
- package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
- package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
- package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
- package/lib/src/src/perspectives/Perspective.d.ts +38 -0
- package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
- package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
- package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
- package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
- package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
- package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
- package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
- package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
- package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
- package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
- package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
- package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
- package/lib/src/src/typeDefs.d.ts +1 -0
- package/lib/src/src/unwrapApolloResult.d.ts +2 -0
- package/lib/src/src/utils.d.ts +25 -0
- package/package.json +20 -24
- package/src/model/Ad4mModel.test.ts +132 -149
- package/src/model/Ad4mModel.ts +1930 -784
- package/src/model/Subject.ts +24 -24
- package/src/model/decorators.ts +626 -482
- package/src/model/util.ts +22 -22
- package/src/neighbourhood/NeighbourhoodClient.ts +32 -16
- package/src/perspectives/PerspectiveProxy.ts +69 -55
- package/src/shacl/SHACLShape.ts +33 -4
package/src/model/Ad4mModel.ts
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { Literal } from "../Literal";
|
|
2
2
|
import { Link } from "../links/Links";
|
|
3
|
+
import { LinkQuery } from "../perspectives/LinkQuery";
|
|
3
4
|
import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
4
|
-
import {
|
|
5
|
-
import { singularToPlural, pluralToSingular, propertyNameToSetterName,
|
|
5
|
+
import { makeRandomId, PropertyOptions, Model, getPropertiesMetadata, getRelationsMetadata, setPropertyRegistryEntry, setRelationRegistryEntry, PropertyMetadataEntry, RelationMetadataEntry } from "./decorators";
|
|
6
|
+
import { singularToPlural, pluralToSingular, propertyNameToSetterName, relationToAdderName, relationToRemoverName, relationToSetterName } from "./util";
|
|
6
7
|
import { escapeSurrealString } from "../utils";
|
|
7
8
|
|
|
8
9
|
// JSON Schema type definitions
|
|
@@ -58,10 +59,47 @@ type WhereCondition = string | number | boolean | string[] | number[] | { [K in
|
|
|
58
59
|
type Where = { [propertyName: string]: WhereCondition };
|
|
59
60
|
type Order = { [propertyName: string]: "ASC" | "DESC" };
|
|
60
61
|
|
|
62
|
+
/**
|
|
63
|
+
* Discriminated union for parent-scoped queries.
|
|
64
|
+
*
|
|
65
|
+
* **Model form** (preferred) — predicate auto-resolved from the parent model's
|
|
66
|
+
* relation metadata. Use `field` to disambiguate when the parent has multiple
|
|
67
|
+
* relations targeting the same child class.
|
|
68
|
+
*
|
|
69
|
+
* **Raw form** — explicit predicate string, no metadata lookup.
|
|
70
|
+
*/
|
|
71
|
+
export type ParentScope =
|
|
72
|
+
| { model: typeof Ad4mModel; id: string; field?: string }
|
|
73
|
+
| { id: string; predicate: string };
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Describes which relations to eager-load when querying.
|
|
77
|
+
*
|
|
78
|
+
* Each value is either:
|
|
79
|
+
* - `true` — hydrate the relation one level deep
|
|
80
|
+
* - A `RelationSubQuery` — scoped sub-query (filter / sort / paginate / nested include)
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* ```typescript
|
|
84
|
+
* // One level deep
|
|
85
|
+
* { comments: true }
|
|
86
|
+
*
|
|
87
|
+
* // Sub-query: only the 5 most-recent comments
|
|
88
|
+
* { comments: { order: { createdAt: 'DESC' }, limit: 5 } }
|
|
89
|
+
*
|
|
90
|
+
* // Nested eager-load
|
|
91
|
+
* { comments: { include: { author: true } } }
|
|
92
|
+
* ```
|
|
93
|
+
*/
|
|
94
|
+
export interface IncludeMap {
|
|
95
|
+
[relation: string]: boolean | RelationSubQuery;
|
|
96
|
+
}
|
|
97
|
+
|
|
61
98
|
export type Query = {
|
|
62
|
-
|
|
99
|
+
/** Filter to instances that are the target of a link from a given parent. */
|
|
100
|
+
parent?: ParentScope;
|
|
63
101
|
properties?: string[];
|
|
64
|
-
|
|
102
|
+
include?: IncludeMap;
|
|
65
103
|
where?: Where;
|
|
66
104
|
order?: Order;
|
|
67
105
|
offset?: number;
|
|
@@ -69,6 +107,26 @@ export type Query = {
|
|
|
69
107
|
count?: boolean;
|
|
70
108
|
};
|
|
71
109
|
|
|
110
|
+
/**
|
|
111
|
+
* Sub-query options for a specific relation inside an `IncludeMap`.
|
|
112
|
+
*
|
|
113
|
+
* Equivalent to `Query` without top-level scoping (`parent`) or `count`,
|
|
114
|
+
* since the result set is already constrained to the linked relation.
|
|
115
|
+
*
|
|
116
|
+
* @example
|
|
117
|
+
* ```typescript
|
|
118
|
+
* await post.get({ include: { comments: { order: { createdAt: 'DESC' }, limit: 5 } } });
|
|
119
|
+
* ```
|
|
120
|
+
*/
|
|
121
|
+
export type RelationSubQuery = Omit<Query, 'parent' | 'count'>;
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Options accepted by the instance `get()` method.
|
|
125
|
+
*
|
|
126
|
+
* A subset of `Query` — only hydration controls apply to a single known instance.
|
|
127
|
+
*/
|
|
128
|
+
export type GetOptions = Pick<Query, 'include' | 'properties'>;
|
|
129
|
+
|
|
72
130
|
export type AllInstancesResult = { AllInstances: Ad4mModel[]; TotalCount?: number; isInit?: boolean };
|
|
73
131
|
export type ResultsWithTotalCount<T> = { results: T[]; totalCount?: number };
|
|
74
132
|
export type PaginationResult<T> = { results: T[]; totalCount?: number; pageSize: number; pageNumber: number };
|
|
@@ -83,8 +141,8 @@ export interface PropertyMetadata {
|
|
|
83
141
|
predicate: string;
|
|
84
142
|
/** Whether the property is required */
|
|
85
143
|
required: boolean;
|
|
86
|
-
/** Whether the property is
|
|
87
|
-
|
|
144
|
+
/** Whether the property is read-only */
|
|
145
|
+
readOnly: boolean;
|
|
88
146
|
/** Initial value if specified */
|
|
89
147
|
initial?: string;
|
|
90
148
|
/** Language for resolution (e.g., "literal") */
|
|
@@ -104,41 +162,87 @@ export interface PropertyMetadata {
|
|
|
104
162
|
}
|
|
105
163
|
|
|
106
164
|
/**
|
|
107
|
-
* Metadata for a single
|
|
165
|
+
* Metadata for a single relation extracted from decorators.
|
|
108
166
|
*/
|
|
109
|
-
export interface
|
|
110
|
-
/** The
|
|
167
|
+
export interface RelationMetadata {
|
|
168
|
+
/** The relation name */
|
|
111
169
|
name: string;
|
|
112
170
|
/** The predicate URI (through value) */
|
|
113
171
|
predicate: string;
|
|
114
|
-
/** Filter conditions */
|
|
115
|
-
where?: { isInstance?: any; prologCondition?: string; condition?: string };
|
|
116
172
|
/** Custom SurrealQL getter code */
|
|
117
173
|
getter?: string;
|
|
118
174
|
/** Whether stored locally only */
|
|
119
175
|
local?: boolean;
|
|
176
|
+
/** Link direction: 'forward' for HasMany/HasOne, 'reverse' for BelongsToMany/BelongsToOne */
|
|
177
|
+
direction?: 'forward' | 'reverse';
|
|
120
178
|
}
|
|
121
179
|
|
|
180
|
+
|
|
181
|
+
|
|
122
182
|
/**
|
|
123
183
|
* Complete model metadata extracted from decorators.
|
|
124
184
|
*/
|
|
125
185
|
export interface ModelMetadata {
|
|
126
|
-
/** The model class name from @
|
|
186
|
+
/** The model class name from @Model */
|
|
127
187
|
className: string;
|
|
128
188
|
/** Map of property name to metadata */
|
|
129
189
|
properties: Record<string, PropertyMetadata>;
|
|
130
|
-
/** Map of
|
|
131
|
-
|
|
190
|
+
/** Map of relation name to metadata */
|
|
191
|
+
relations: Record<string, RelationMetadata>;
|
|
132
192
|
}
|
|
133
193
|
|
|
134
194
|
function capitalize(word: string): string {
|
|
135
195
|
return word.charAt(0).toUpperCase() + word.slice(1);
|
|
136
196
|
}
|
|
137
197
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
198
|
+
/**
|
|
199
|
+
* Resolves the predicate for a parent query.
|
|
200
|
+
*
|
|
201
|
+
* Uses TS discriminated union narrowing:
|
|
202
|
+
* - Raw form (`{ id, predicate }`) → predicate used as-is
|
|
203
|
+
* - Model form (`{ model, id, field? }`) → lookup from relation metadata
|
|
204
|
+
* - With `field`: direct key lookup
|
|
205
|
+
* - Without `field`: scan for a relation whose `target()` matches `childCtor`
|
|
206
|
+
*/
|
|
207
|
+
function resolveParentPredicate(
|
|
208
|
+
parent: ParentScope,
|
|
209
|
+
childCtor: Function,
|
|
210
|
+
): string {
|
|
211
|
+
// Raw form — explicit predicate
|
|
212
|
+
if ('predicate' in parent) return parent.predicate;
|
|
213
|
+
|
|
214
|
+
// Model form — resolve from relation metadata
|
|
215
|
+
const { model } = parent;
|
|
216
|
+
const relMeta = getRelationsMetadata(model);
|
|
217
|
+
|
|
218
|
+
// Direct lookup by field name when provided
|
|
219
|
+
if (parent.field) {
|
|
220
|
+
const entry = relMeta[parent.field];
|
|
221
|
+
if (!entry) {
|
|
222
|
+
throw new Error(
|
|
223
|
+
`parent(): field "${parent.field}" is not a registered relation on ${model.name}`,
|
|
224
|
+
);
|
|
225
|
+
}
|
|
226
|
+
return entry.predicate;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
// Fallback: scan for a relation whose target matches the child class
|
|
230
|
+
for (const [, entry] of Object.entries(relMeta)) {
|
|
231
|
+
if (entry.target && entry.target() === childCtor) {
|
|
232
|
+
return entry.predicate;
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
throw new Error(
|
|
236
|
+
`parent(): could not resolve predicate — no relation on ${model.name} targets ${(childCtor as any).name || 'the queried class'}`,
|
|
237
|
+
);
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
function buildParentQuery(
|
|
241
|
+
parent: ParentScope | undefined,
|
|
242
|
+
resolvedPredicate?: string,
|
|
243
|
+
): string {
|
|
244
|
+
if (!parent || !resolvedPredicate) return '';
|
|
245
|
+
return `triple("${parent.id}", "${resolvedPredicate}", Base)`;
|
|
142
246
|
}
|
|
143
247
|
|
|
144
248
|
// todo: only return Timestamp & Author from query (Base, AllLinks, and SortLinks not required)
|
|
@@ -169,22 +273,9 @@ function buildPropertiesQuery(properties?: string[]): string {
|
|
|
169
273
|
`;
|
|
170
274
|
}
|
|
171
275
|
|
|
172
|
-
function buildCollectionsQuery(collections?: string[]): string {
|
|
173
|
-
// Gets the name and array of values for all (or some) collections on a Ad4mModel instance
|
|
174
|
-
// If no collections are provided, all are included
|
|
175
|
-
return `
|
|
176
|
-
findall([CollectionName, CollectionValues], (
|
|
177
|
-
% Constrain to specified collections if provided
|
|
178
|
-
${collections ? `member(CollectionName, [${collections.map((name) => `"${name}"`).join(", ")}]),` : ""}
|
|
179
|
-
|
|
180
|
-
collection(SubjectClass, CollectionName),
|
|
181
|
-
collection_getter(SubjectClass, Base, CollectionName, CollectionValues)
|
|
182
|
-
), Collections)
|
|
183
|
-
`;
|
|
184
|
-
}
|
|
185
|
-
|
|
186
276
|
function buildWhereQuery(where: Where = {}): string {
|
|
187
277
|
// Constrains the query to instances that match the provided where conditions
|
|
278
|
+
// 'id' maps to the Prolog 'Base' variable (the base expression of the instance).
|
|
188
279
|
|
|
189
280
|
function formatValue(value) {
|
|
190
281
|
// Wrap strings in quotes
|
|
@@ -193,10 +284,10 @@ function buildWhereQuery(where: Where = {}): string {
|
|
|
193
284
|
|
|
194
285
|
return (Object.entries(where) as [string, WhereCondition][])
|
|
195
286
|
.map(([key, value]) => {
|
|
196
|
-
const isSpecial = ["
|
|
287
|
+
const isSpecial = ["id", "author", "timestamp"].includes(key);
|
|
197
288
|
const getter = `resolve_property(SubjectClass, Base, "${key}", Value${key}, _)`;
|
|
198
|
-
//
|
|
199
|
-
const field = capitalize(key);
|
|
289
|
+
// For 'id' the Prolog variable is always 'Base'
|
|
290
|
+
const field = key === "id" ? "Base" : capitalize(key);
|
|
200
291
|
|
|
201
292
|
// Handle direct array values (for IN conditions)
|
|
202
293
|
if (Array.isArray(value)) {
|
|
@@ -256,8 +347,22 @@ function buildCountQuery(count?: boolean): string {
|
|
|
256
347
|
|
|
257
348
|
function buildOrderQuery(order?: Order): string {
|
|
258
349
|
if (!order) return "SortedInstances = UnsortedInstances";
|
|
259
|
-
const
|
|
260
|
-
|
|
350
|
+
const entries = Object.entries(order);
|
|
351
|
+
if (entries.length === 1) {
|
|
352
|
+
const [propertyName, direction] = entries[0];
|
|
353
|
+
return `sort_instances(UnsortedInstances, "${propertyName}", "${direction}", SortedInstances)`;
|
|
354
|
+
}
|
|
355
|
+
// Multi-field sort: sort from least-significant to most-significant key
|
|
356
|
+
// so that the final (primary) sort preserves secondary-key ordering for equal values.
|
|
357
|
+
// The merge_sort implementation is stable (equal elements keep original order).
|
|
358
|
+
const clauses: string[] = [];
|
|
359
|
+
for (let i = entries.length - 1; i >= 0; i--) {
|
|
360
|
+
const [propertyName, direction] = entries[i];
|
|
361
|
+
const inputVar = i === entries.length - 1 ? "UnsortedInstances" : `MultiSortIntermediate${i + 1}`;
|
|
362
|
+
const outputVar = i === 0 ? "SortedInstances" : `MultiSortIntermediate${i}`;
|
|
363
|
+
clauses.push(`sort_instances(${inputVar}, "${propertyName}", "${direction}", ${outputVar})`);
|
|
364
|
+
}
|
|
365
|
+
return clauses.join(",\n ");
|
|
261
366
|
}
|
|
262
367
|
|
|
263
368
|
function buildOffsetQuery(offset?: number): string {
|
|
@@ -313,21 +418,21 @@ function isNumericType(schema: JSONSchemaProperty): boolean {
|
|
|
313
418
|
*
|
|
314
419
|
* @description
|
|
315
420
|
* Ad4mModel provides the foundation for creating data models that are stored in AD4M perspectives.
|
|
316
|
-
* Each model instance is represented as a subgraph in the perspective, with properties and
|
|
421
|
+
* Each model instance is represented as a subgraph in the perspective, with properties and relations
|
|
317
422
|
* mapped to links in that graph. The class uses Prolog-based queries to efficiently search and filter
|
|
318
423
|
* instances based on their properties and relationships.
|
|
319
424
|
*
|
|
320
425
|
* Key concepts:
|
|
321
426
|
* - Each model instance has a unique base expression that serves as its identifier
|
|
322
427
|
* - Properties are stored as links with predicates defined by the `through` option
|
|
323
|
-
* -
|
|
428
|
+
* - Relations represent one-to-many relationships as sets of links
|
|
324
429
|
* - Queries are translated to Prolog for efficient graph pattern matching
|
|
325
430
|
* - Changes are tracked through the perspective's subscription system
|
|
326
431
|
*
|
|
327
432
|
* @example
|
|
328
433
|
* ```typescript
|
|
329
434
|
* // Define a recipe model
|
|
330
|
-
* @
|
|
435
|
+
* @Model({ name: "Recipe" })
|
|
331
436
|
* class Recipe extends Ad4mModel {
|
|
332
437
|
* // Required property with literal value
|
|
333
438
|
* @Property({
|
|
@@ -355,15 +460,12 @@ function isNumericType(schema: JSONSchemaProperty): boolean {
|
|
|
355
460
|
* })
|
|
356
461
|
* averageRating: number = 0;
|
|
357
462
|
*
|
|
358
|
-
* //
|
|
359
|
-
|
|
360
|
-
|
|
463
|
+
* // Relation of ingredients
|
|
464
|
+
* @HasMany({ through: "recipe://ingredient" })
|
|
465
|
+
* ingredients: string[] = [];
|
|
361
466
|
*
|
|
362
|
-
* //
|
|
363
|
-
* @
|
|
364
|
-
* through: "recipe://comment",
|
|
365
|
-
* where: { isInstance: Comment }
|
|
366
|
-
* })
|
|
467
|
+
* // Relation of comments linked to another model
|
|
468
|
+
* @HasMany(() => Comment, { through: "recipe://comment" })
|
|
367
469
|
* comments: Comment[] = [];
|
|
368
470
|
* }
|
|
369
471
|
*
|
|
@@ -408,16 +510,35 @@ function isNumericType(schema: JSONSchemaProperty): boolean {
|
|
|
408
510
|
* ```
|
|
409
511
|
*/
|
|
410
512
|
export class Ad4mModel {
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
513
|
+
private _baseExpression: string;
|
|
514
|
+
private _subjectClassName: string;
|
|
515
|
+
private _perspective: PerspectiveProxy;
|
|
516
|
+
private _snapshot: Record<string, any> | null = null;
|
|
415
517
|
author: string;
|
|
416
518
|
createdAt: any;
|
|
417
519
|
updatedAt: any;
|
|
418
520
|
|
|
419
521
|
private static classNamesByClass = new WeakMap<typeof Ad4mModel, { [perspectiveId: string]: string }>();
|
|
420
522
|
|
|
523
|
+
/**
|
|
524
|
+
* Generates the SDNA (Subject DNA) Prolog rules for this model class.
|
|
525
|
+
* Injected at class-definition time by the `@Model` decorator.
|
|
526
|
+
* Returns a default value on un-decorated base classes.
|
|
527
|
+
*/
|
|
528
|
+
static generateSDNA(): { sdna: string; name: string } {
|
|
529
|
+
return { sdna: '', name: '' };
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
/**
|
|
533
|
+
* Generates the SHACL shape graph for this model class.
|
|
534
|
+
* Injected at class-definition time by the `@Model` decorator.
|
|
535
|
+
* Returns `{ shape: null, name: '' }` on un-decorated base classes —
|
|
536
|
+
* the decorator's `parentSHACL?.shape?.nodeShapeUri` check handles this.
|
|
537
|
+
*/
|
|
538
|
+
static generateSHACL(): { shape: any; name: string } {
|
|
539
|
+
return { shape: null, name: '' };
|
|
540
|
+
}
|
|
541
|
+
|
|
421
542
|
static async getClassName(perspective: PerspectiveProxy) {
|
|
422
543
|
// Check if this is the Ad4mModel class itself or a subclass
|
|
423
544
|
const isBaseClass = this === Ad4mModel;
|
|
@@ -455,64 +576,64 @@ export class Ad4mModel {
|
|
|
455
576
|
* Extracts metadata from decorators for query building.
|
|
456
577
|
*
|
|
457
578
|
* @description
|
|
458
|
-
* This method reads the metadata stored by decorators (@Property, @
|
|
579
|
+
* This method reads the metadata stored by decorators (@Property, @HasMany, etc.)
|
|
459
580
|
* and returns it in a structured format that's easier to work with for query builders
|
|
460
581
|
* and other systems that need to introspect model structure.
|
|
461
582
|
*
|
|
462
583
|
* The metadata includes:
|
|
463
|
-
* - Class name from @
|
|
584
|
+
* - Class name from @Model
|
|
464
585
|
* - Property metadata (predicates, types, constraints, etc.)
|
|
465
|
-
* -
|
|
586
|
+
* - Relation metadata (predicates, filters, etc.)
|
|
466
587
|
*
|
|
467
588
|
* For models created via `fromJSONSchema()`, this method will derive metadata from
|
|
468
|
-
* the
|
|
469
|
-
*
|
|
470
|
-
*
|
|
589
|
+
* the WeakMap registries that were populated during the dynamic class creation.
|
|
590
|
+
* If these structures are empty but a JSON schema was attached to the class,
|
|
591
|
+
* it can fall back to deriving metadata from that schema.
|
|
471
592
|
*
|
|
472
|
-
* @returns Structured metadata object containing className, properties, and
|
|
473
|
-
* @throws Error if the class doesn't have @
|
|
593
|
+
* @returns Structured metadata object containing className, properties, and relations
|
|
594
|
+
* @throws Error if the class doesn't have @Model decorator
|
|
474
595
|
*
|
|
475
596
|
* @example
|
|
476
597
|
* ```typescript
|
|
477
|
-
* @
|
|
598
|
+
* @Model({ name: "Recipe" })
|
|
478
599
|
* class Recipe extends Ad4mModel {
|
|
479
600
|
* @Property({ through: "recipe://name", resolveLanguage: "literal" })
|
|
480
601
|
* name: string = "";
|
|
481
602
|
*
|
|
482
|
-
* @
|
|
603
|
+
* @HasMany({ through: "recipe://ingredient" })
|
|
483
604
|
* ingredients: string[] = [];
|
|
484
605
|
* }
|
|
485
606
|
*
|
|
486
607
|
* const metadata = Recipe.getModelMetadata();
|
|
487
608
|
* console.log(metadata.className); // "Recipe"
|
|
488
609
|
* console.log(metadata.properties.name.predicate); // "recipe://name"
|
|
489
|
-
* console.log(metadata.
|
|
610
|
+
* console.log(metadata.relations.ingredients.predicate); // "recipe://ingredient"
|
|
490
611
|
* ```
|
|
491
612
|
*/
|
|
492
613
|
public static getModelMetadata(): ModelMetadata {
|
|
493
614
|
// Access the prototype with any type to access decorator-added properties
|
|
494
615
|
const prototype = this.prototype as any;
|
|
495
616
|
|
|
496
|
-
// Validate that the class has @
|
|
617
|
+
// Validate that the class has @Model decorator
|
|
497
618
|
// The decorator sets prototype.className, so we check for its existence
|
|
498
619
|
if (!prototype.className || prototype.className === 'Ad4mModel') {
|
|
499
|
-
throw new Error("Model class must be decorated with @
|
|
620
|
+
throw new Error("Model class must be decorated with @Model");
|
|
500
621
|
}
|
|
501
622
|
|
|
502
623
|
// Extract className
|
|
503
624
|
const className = prototype.className;
|
|
504
625
|
|
|
505
|
-
// Extract properties from
|
|
626
|
+
// Extract properties from WeakMap registry
|
|
506
627
|
const propertiesMetadata: Record<string, PropertyMetadata> = {};
|
|
507
|
-
const prototypeProperties =
|
|
628
|
+
const prototypeProperties = getPropertiesMetadata(this);
|
|
508
629
|
|
|
509
630
|
for (const [propertyName, opts] of Object.entries(prototypeProperties)) {
|
|
510
|
-
const options = opts as PropertyOptions & { required?: boolean; flag?: boolean };
|
|
631
|
+
const options = opts as PropertyOptions & { required?: boolean; flag?: boolean; writable?: boolean };
|
|
511
632
|
propertiesMetadata[propertyName] = {
|
|
512
633
|
name: propertyName,
|
|
513
634
|
predicate: options.through || "",
|
|
514
635
|
required: options.required || false,
|
|
515
|
-
|
|
636
|
+
readOnly: !(options.writable ?? false),
|
|
516
637
|
...(options.initial !== undefined && { initial: options.initial }),
|
|
517
638
|
...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
|
|
518
639
|
...(options.prologGetter !== undefined && { prologGetter: options.prologGetter }),
|
|
@@ -524,26 +645,29 @@ export class Ad4mModel {
|
|
|
524
645
|
};
|
|
525
646
|
}
|
|
526
647
|
|
|
527
|
-
// Extract
|
|
528
|
-
const
|
|
529
|
-
const
|
|
648
|
+
// Extract relations (relations) from WeakMap registry
|
|
649
|
+
const relationsMetadata: Record<string, RelationMetadata> = {};
|
|
650
|
+
const allRelationsMeta = getRelationsMetadata(this as any);
|
|
651
|
+
const prototypeRelations = Object.fromEntries(
|
|
652
|
+
Object.entries(allRelationsMeta).filter(([, r]) => r.kind === 'hasMany' || r.kind === 'belongsToMany')
|
|
653
|
+
);
|
|
530
654
|
|
|
531
|
-
for (const [
|
|
532
|
-
const options = opts as
|
|
533
|
-
|
|
534
|
-
name:
|
|
535
|
-
predicate: options.
|
|
536
|
-
...(options.where !== undefined && { where: options.where }),
|
|
655
|
+
for (const [relationName, opts] of Object.entries(prototypeRelations)) {
|
|
656
|
+
const options = opts as RelationMetadataEntry;
|
|
657
|
+
relationsMetadata[relationName] = {
|
|
658
|
+
name: relationName,
|
|
659
|
+
predicate: options.predicate || "",
|
|
537
660
|
...(options.local !== undefined && { local: options.local }),
|
|
538
|
-
...(options.getter !== undefined && { getter: options.getter })
|
|
661
|
+
...(options.getter !== undefined && { getter: options.getter }),
|
|
662
|
+
direction: (options.kind === 'belongsToMany' || options.kind === 'belongsToOne') ? 'reverse' : 'forward',
|
|
539
663
|
};
|
|
540
664
|
}
|
|
541
665
|
|
|
542
666
|
// Fallback: If both structures are empty but a JSON schema is attached, derive from it
|
|
543
667
|
// This handles edge cases where fromJSONSchema() was called but metadata wasn't properly populated
|
|
544
668
|
const hasProperties = Object.keys(propertiesMetadata).length > 0;
|
|
545
|
-
const
|
|
546
|
-
const hasMetadata = hasProperties ||
|
|
669
|
+
const hasRelations = Object.keys(relationsMetadata).length > 0;
|
|
670
|
+
const hasMetadata = hasProperties || hasRelations;
|
|
547
671
|
|
|
548
672
|
if (!hasMetadata && prototype.__jsonSchema) {
|
|
549
673
|
// Derive metadata from the attached JSON schema
|
|
@@ -562,7 +686,7 @@ export class Ad4mModel {
|
|
|
562
686
|
);
|
|
563
687
|
|
|
564
688
|
if (isArray) {
|
|
565
|
-
|
|
689
|
+
relationsMetadata[propertyName] = {
|
|
566
690
|
name: propertyName,
|
|
567
691
|
predicate: predicate,
|
|
568
692
|
...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
|
|
@@ -573,7 +697,7 @@ export class Ad4mModel {
|
|
|
573
697
|
name: propertyName,
|
|
574
698
|
predicate: predicate,
|
|
575
699
|
required: isRequired,
|
|
576
|
-
|
|
700
|
+
readOnly: propertySchema["x-ad4m"]?.writable === false,
|
|
577
701
|
...(propertySchema["x-ad4m"]?.resolveLanguage && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
|
|
578
702
|
...(propertySchema["x-ad4m"]?.initial && { initial: propertySchema["x-ad4m"].initial }),
|
|
579
703
|
...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
|
|
@@ -586,7 +710,7 @@ export class Ad4mModel {
|
|
|
586
710
|
return {
|
|
587
711
|
className,
|
|
588
712
|
properties: propertiesMetadata,
|
|
589
|
-
|
|
713
|
+
relations: relationsMetadata,
|
|
590
714
|
};
|
|
591
715
|
}
|
|
592
716
|
|
|
@@ -594,7 +718,8 @@ export class Ad4mModel {
|
|
|
594
718
|
* Constructs a new model instance.
|
|
595
719
|
*
|
|
596
720
|
* @param perspective - The perspective where this model will be stored
|
|
597
|
-
* @param baseExpression - Optional
|
|
721
|
+
* @param baseExpression - Optional expression URI for this instance.
|
|
722
|
+
* If omitted, a random Literal URL is generated.
|
|
598
723
|
* @param source - Optional source expression this instance is linked to
|
|
599
724
|
*
|
|
600
725
|
* @example
|
|
@@ -603,23 +728,26 @@ export class Ad4mModel {
|
|
|
603
728
|
* const recipe = new Recipe(perspective);
|
|
604
729
|
*
|
|
605
730
|
* // Create with specific base expression
|
|
606
|
-
* const recipe = new Recipe(perspective, "
|
|
607
|
-
*
|
|
608
|
-
* // Create with source link
|
|
609
|
-
* const recipe = new Recipe(perspective, undefined, "cookbook://desserts");
|
|
731
|
+
* const recipe = new Recipe(perspective, "literal://...");
|
|
610
732
|
* ```
|
|
611
733
|
*/
|
|
612
|
-
constructor(perspective: PerspectiveProxy, baseExpression?: string
|
|
613
|
-
this
|
|
614
|
-
this
|
|
615
|
-
|
|
734
|
+
constructor(perspective: PerspectiveProxy, baseExpression?: string) {
|
|
735
|
+
this._baseExpression = baseExpression ? baseExpression : Literal.from(makeRandomId(24)).toUrl();
|
|
736
|
+
this._perspective = perspective;
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
/**
|
|
740
|
+
* The unique identifier (expression URI) of this model instance.
|
|
741
|
+
*/
|
|
742
|
+
get id(): string {
|
|
743
|
+
return this._baseExpression;
|
|
616
744
|
}
|
|
617
745
|
|
|
618
746
|
/**
|
|
619
|
-
*
|
|
747
|
+
* @deprecated Use `.id` instead. Will be removed in a future version.
|
|
620
748
|
*/
|
|
621
|
-
get baseExpression() {
|
|
622
|
-
return this
|
|
749
|
+
get baseExpression(): string {
|
|
750
|
+
return this._baseExpression;
|
|
623
751
|
}
|
|
624
752
|
|
|
625
753
|
/**
|
|
@@ -627,25 +755,27 @@ export class Ad4mModel {
|
|
|
627
755
|
* Allows subclasses to access the perspective while keeping it private from external code.
|
|
628
756
|
*/
|
|
629
757
|
protected get perspective(): PerspectiveProxy {
|
|
630
|
-
return this
|
|
758
|
+
return this._perspective;
|
|
631
759
|
}
|
|
632
760
|
|
|
633
761
|
/**
|
|
634
762
|
* Get property metadata from decorator (Phase 1: Prolog-free refactor)
|
|
635
763
|
* @private
|
|
636
764
|
*/
|
|
637
|
-
private getPropertyMetadata(key: string):
|
|
638
|
-
const
|
|
639
|
-
|
|
765
|
+
private getPropertyMetadata(key: string): PropertyMetadataEntry | undefined {
|
|
766
|
+
const ctor = this.constructor;
|
|
767
|
+
const props = getPropertiesMetadata(ctor);
|
|
768
|
+
return props[key];
|
|
640
769
|
}
|
|
641
770
|
|
|
642
771
|
/**
|
|
643
|
-
* Get
|
|
772
|
+
* Get relation options from decorator
|
|
644
773
|
* @private
|
|
645
774
|
*/
|
|
646
|
-
private
|
|
647
|
-
const
|
|
648
|
-
|
|
775
|
+
private getRelationOptions(key: string): RelationMetadataEntry | undefined {
|
|
776
|
+
const ctor = this.constructor;
|
|
777
|
+
const rels = getRelationsMetadata(ctor);
|
|
778
|
+
return rels[key];
|
|
649
779
|
}
|
|
650
780
|
|
|
651
781
|
/**
|
|
@@ -653,9 +783,17 @@ export class Ad4mModel {
|
|
|
653
783
|
* Replaces Prolog query: property_setter(C, key, Setter)
|
|
654
784
|
* @private
|
|
655
785
|
*/
|
|
656
|
-
private generatePropertySetterAction(key: string, metadata:
|
|
786
|
+
private generatePropertySetterAction(key: string, metadata: PropertyMetadataEntry): any[] {
|
|
787
|
+
// Flags are always immutable — throw a clear error
|
|
788
|
+
if (metadata.flag) {
|
|
789
|
+
throw new Error(
|
|
790
|
+
`Property "${key}" is a @Flag and cannot be written. ` +
|
|
791
|
+
`Flags are immutable type markers set at creation time.`
|
|
792
|
+
);
|
|
793
|
+
}
|
|
794
|
+
|
|
657
795
|
// Check if property is read-only
|
|
658
|
-
if (metadata.
|
|
796
|
+
if (metadata.readOnly) {
|
|
659
797
|
throw new Error(`Property "${key}" is read-only and cannot be written`);
|
|
660
798
|
}
|
|
661
799
|
|
|
@@ -681,18 +819,18 @@ export class Ad4mModel {
|
|
|
681
819
|
}
|
|
682
820
|
|
|
683
821
|
/**
|
|
684
|
-
* Generate
|
|
822
|
+
* Generate relation action from metadata (Phase 1: Prolog-free refactor)
|
|
685
823
|
* Replaces Prolog queries: collection_adder, collection_remover, collection_setter
|
|
686
824
|
* @private
|
|
687
825
|
*/
|
|
688
|
-
private
|
|
689
|
-
const metadata = this.
|
|
826
|
+
private generateRelationAction(key: string, actionType: 'adder' | 'remover' | 'setter'): any[] {
|
|
827
|
+
const metadata = this.getRelationOptions(key);
|
|
690
828
|
if (!metadata) {
|
|
691
|
-
throw new Error(`
|
|
829
|
+
throw new Error(`Relation "${key}" has no metadata defined`);
|
|
692
830
|
}
|
|
693
831
|
|
|
694
|
-
if (!metadata.
|
|
695
|
-
throw new Error(`
|
|
832
|
+
if (!metadata.predicate) {
|
|
833
|
+
throw new Error(`Relation "${key}" has no predicate defined`);
|
|
696
834
|
}
|
|
697
835
|
|
|
698
836
|
const actionMap = {
|
|
@@ -704,12 +842,229 @@ export class Ad4mModel {
|
|
|
704
842
|
return [{
|
|
705
843
|
action: actionMap[actionType],
|
|
706
844
|
source: "this",
|
|
707
|
-
predicate: metadata.
|
|
845
|
+
predicate: metadata.predicate,
|
|
708
846
|
target: "value",
|
|
709
847
|
...(metadata.local && { local: true })
|
|
710
848
|
}];
|
|
711
849
|
}
|
|
712
850
|
|
|
851
|
+
// ──────────────────────────────────────────────────────────
|
|
852
|
+
// Unified hydration helpers
|
|
853
|
+
// ──────────────────────────────────────────────────────────
|
|
854
|
+
|
|
855
|
+
/**
|
|
856
|
+
* Resolves a raw link target value into a hydrated property value.
|
|
857
|
+
*
|
|
858
|
+
* Handles, in order:
|
|
859
|
+
* 1. Non-literal expression resolution (`perspective.getExpression`)
|
|
860
|
+
* 2. Literal URI parsing (`Literal.fromUrl(…).get()`)
|
|
861
|
+
* 3. Primitive type coercion (string → number / boolean)
|
|
862
|
+
* 4. Transform function application
|
|
863
|
+
*
|
|
864
|
+
* @param target - The raw target string from the link
|
|
865
|
+
* @param propMeta - Property metadata from the decorator registry
|
|
866
|
+
* @param perspective - The perspective for expression resolution
|
|
867
|
+
* @param expectedType - Optional JS typeof hint for coercion (e.g. 'number')
|
|
868
|
+
* @returns The resolved value
|
|
869
|
+
* @private
|
|
870
|
+
*/
|
|
871
|
+
private static async hydratePropertyValue(
|
|
872
|
+
target: string,
|
|
873
|
+
propMeta: PropertyMetadata,
|
|
874
|
+
perspective: PerspectiveProxy,
|
|
875
|
+
expectedType?: string,
|
|
876
|
+
): Promise<any> {
|
|
877
|
+
let value: any = target;
|
|
878
|
+
|
|
879
|
+
if (target !== undefined && target !== null && target !== '') {
|
|
880
|
+
// Non-literal expression resolution
|
|
881
|
+
if (
|
|
882
|
+
propMeta.resolveLanguage != null &&
|
|
883
|
+
propMeta.resolveLanguage !== 'literal' &&
|
|
884
|
+
typeof target === 'string' &&
|
|
885
|
+
!target.startsWith('literal://')
|
|
886
|
+
) {
|
|
887
|
+
try {
|
|
888
|
+
const expression = await perspective.getExpression(target);
|
|
889
|
+
if (expression) {
|
|
890
|
+
try { value = JSON.parse(expression.data); } catch { value = expression.data; }
|
|
891
|
+
}
|
|
892
|
+
} catch (e) {
|
|
893
|
+
console.warn(`hydratePropertyValue: failed to resolve expression for "${propMeta.name}":`, e);
|
|
894
|
+
}
|
|
895
|
+
}
|
|
896
|
+
// Literal URI parsing
|
|
897
|
+
else if (
|
|
898
|
+
propMeta.resolveLanguage === 'literal' &&
|
|
899
|
+
typeof target === 'string' &&
|
|
900
|
+
target.startsWith('literal://')
|
|
901
|
+
) {
|
|
902
|
+
try {
|
|
903
|
+
const parsed = Literal.fromUrl(target).get();
|
|
904
|
+
value = parsed.data !== undefined ? parsed.data : parsed;
|
|
905
|
+
} catch {
|
|
906
|
+
// Keep raw value
|
|
907
|
+
}
|
|
908
|
+
}
|
|
909
|
+
// Primitive type coercion
|
|
910
|
+
else if (typeof target === 'string' && expectedType) {
|
|
911
|
+
if (expectedType === 'number') value = Number(target);
|
|
912
|
+
else if (expectedType === 'boolean') value = target === 'true' || target === '1';
|
|
913
|
+
}
|
|
914
|
+
}
|
|
915
|
+
|
|
916
|
+
// Transform function
|
|
917
|
+
if (propMeta.transform && typeof propMeta.transform === 'function') {
|
|
918
|
+
value = propMeta.transform(value);
|
|
919
|
+
}
|
|
920
|
+
|
|
921
|
+
return value;
|
|
922
|
+
}
|
|
923
|
+
|
|
924
|
+
/**
|
|
925
|
+
* Link shape accepted by `hydrateFromLinks`.
|
|
926
|
+
* Both `getData()` and `instancesFromSurrealResult()` produce this shape.
|
|
927
|
+
*/
|
|
928
|
+
private static readonly _linkShape: undefined; // type-only marker
|
|
929
|
+
|
|
930
|
+
/**
|
|
931
|
+
* Hydrates an instance from an array of raw links.
|
|
932
|
+
*
|
|
933
|
+
* Processes properties (latest-wins semantics), relations
|
|
934
|
+
* (chronological accumulation), and timestamps/author in a single
|
|
935
|
+
* pass over the links array.
|
|
936
|
+
*
|
|
937
|
+
* @param instance - The blank model instance to populate
|
|
938
|
+
* @param links - Array of link objects (predicate, target, author?, timestamp?)
|
|
939
|
+
* @param metadata - Model metadata from `getModelMetadata()`
|
|
940
|
+
* @param perspective - The perspective for expression resolution
|
|
941
|
+
* @param requestedProperties - Optional sparse fieldset; when provided, only these
|
|
942
|
+
* property names are hydrated (relations are unaffected).
|
|
943
|
+
* Omit or pass `undefined` to hydrate all properties.
|
|
944
|
+
* @private
|
|
945
|
+
*/
|
|
946
|
+
private static async hydrateFromLinks(
|
|
947
|
+
instance: any,
|
|
948
|
+
links: Array<{ predicate: string; target: string; author?: string; timestamp?: string | number }>,
|
|
949
|
+
metadata: ModelMetadata,
|
|
950
|
+
perspective: PerspectiveProxy,
|
|
951
|
+
requestedProperties?: string[],
|
|
952
|
+
): Promise<void> {
|
|
953
|
+
if (!links || links.length === 0) return;
|
|
954
|
+
|
|
955
|
+
let minTimestamp: string | number | null = null;
|
|
956
|
+
let maxTimestamp: string | number | null = null;
|
|
957
|
+
let originalAuthor: string | null = null;
|
|
958
|
+
let latestAuthor: string | null = null;
|
|
959
|
+
|
|
960
|
+
// Build predicate→propName and predicate→relName lookup maps for O(1) matching
|
|
961
|
+
// When requestedProperties is provided, only include those properties in the map
|
|
962
|
+
const propFilter = requestedProperties && requestedProperties.length > 0
|
|
963
|
+
? new Set(requestedProperties)
|
|
964
|
+
: null;
|
|
965
|
+
|
|
966
|
+
const predToProperty = new Map<string, [string, PropertyMetadata]>();
|
|
967
|
+
for (const [propName, propMeta] of Object.entries(metadata.properties)) {
|
|
968
|
+
if (propMeta.getter) continue; // Handled via custom getter evaluation
|
|
969
|
+
if (propFilter && !propFilter.has(propName)) continue; // Skip unrequested properties
|
|
970
|
+
predToProperty.set(propMeta.predicate, [propName, propMeta]);
|
|
971
|
+
}
|
|
972
|
+
|
|
973
|
+
const predToRelation = new Map<string, [string, RelationMetadata]>();
|
|
974
|
+
for (const [relName, relMeta] of Object.entries(metadata.relations)) {
|
|
975
|
+
if (relMeta.getter) continue;
|
|
976
|
+
predToRelation.set(relMeta.predicate, [relName, relMeta]);
|
|
977
|
+
}
|
|
978
|
+
|
|
979
|
+
// Per-property accumulator: track all matching targets so we can pick the last (latest-wins)
|
|
980
|
+
const propertyLatest = new Map<string, { target: string; timestamp?: string | number }>();
|
|
981
|
+
|
|
982
|
+
// Per-relation accumulator: ordered targets with metadata for sorting
|
|
983
|
+
const relationAccum = new Map<string, Array<{ target: string; timestamp: string | number; index: number }>>();
|
|
984
|
+
|
|
985
|
+
// Single pass over all links
|
|
986
|
+
for (let i = 0; i < links.length; i++) {
|
|
987
|
+
const link = links[i];
|
|
988
|
+
const { predicate, target, author, timestamp } = link;
|
|
989
|
+
if (target === 'None' || target === undefined || target === null) continue;
|
|
990
|
+
|
|
991
|
+
// Track timestamps/authors
|
|
992
|
+
if (timestamp != null) {
|
|
993
|
+
if (minTimestamp == null || timestamp < minTimestamp) {
|
|
994
|
+
minTimestamp = timestamp;
|
|
995
|
+
originalAuthor = author ?? null;
|
|
996
|
+
}
|
|
997
|
+
if (maxTimestamp == null || timestamp > maxTimestamp) {
|
|
998
|
+
maxTimestamp = timestamp;
|
|
999
|
+
latestAuthor = author ?? null;
|
|
1000
|
+
}
|
|
1001
|
+
}
|
|
1002
|
+
|
|
1003
|
+
// Property match — accumulate for latest-wins
|
|
1004
|
+
const propEntry = predToProperty.get(predicate);
|
|
1005
|
+
if (propEntry) {
|
|
1006
|
+
const existing = propertyLatest.get(propEntry[0]);
|
|
1007
|
+
// Latest-wins: always overwrite (links are ordered ASC so last = latest)
|
|
1008
|
+
propertyLatest.set(propEntry[0], { target, timestamp });
|
|
1009
|
+
continue;
|
|
1010
|
+
}
|
|
1011
|
+
|
|
1012
|
+
// Relation match — accumulate all
|
|
1013
|
+
const relEntry = predToRelation.get(predicate);
|
|
1014
|
+
if (relEntry) {
|
|
1015
|
+
const [relName] = relEntry;
|
|
1016
|
+
let arr = relationAccum.get(relName);
|
|
1017
|
+
if (!arr) {
|
|
1018
|
+
arr = [];
|
|
1019
|
+
relationAccum.set(relName, arr);
|
|
1020
|
+
}
|
|
1021
|
+
arr.push({ target, timestamp: timestamp ?? '', index: i });
|
|
1022
|
+
}
|
|
1023
|
+
}
|
|
1024
|
+
|
|
1025
|
+
// Resolve properties
|
|
1026
|
+
for (const [propName, { target }] of propertyLatest) {
|
|
1027
|
+
const [, propMeta] = predToProperty.get(
|
|
1028
|
+
metadata.properties[propName].predicate
|
|
1029
|
+
)!;
|
|
1030
|
+
const expectedType = typeof instance[propName];
|
|
1031
|
+
instance[propName] = await this.hydratePropertyValue(
|
|
1032
|
+
target,
|
|
1033
|
+
propMeta,
|
|
1034
|
+
perspective,
|
|
1035
|
+
expectedType !== 'undefined' ? expectedType : undefined,
|
|
1036
|
+
);
|
|
1037
|
+
}
|
|
1038
|
+
|
|
1039
|
+
// Resolve relations: sort by timestamp (stable via index tiebreaker), filter empties
|
|
1040
|
+
for (const [relName, items] of relationAccum) {
|
|
1041
|
+
items.sort((a, b) => {
|
|
1042
|
+
const cmp = String(a.timestamp).localeCompare(String(b.timestamp));
|
|
1043
|
+
return cmp !== 0 ? cmp : a.index - b.index;
|
|
1044
|
+
});
|
|
1045
|
+
instance[relName] = items
|
|
1046
|
+
.map(i => i.target)
|
|
1047
|
+
.filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None');
|
|
1048
|
+
}
|
|
1049
|
+
|
|
1050
|
+
// Assign author / timestamps
|
|
1051
|
+
if (originalAuthor) instance.author = originalAuthor;
|
|
1052
|
+
if (minTimestamp != null) {
|
|
1053
|
+
instance.createdAt = typeof minTimestamp === 'string' && minTimestamp.includes('T')
|
|
1054
|
+
? new Date(minTimestamp).getTime()
|
|
1055
|
+
: typeof minTimestamp === 'string'
|
|
1056
|
+
? (isNaN(parseInt(minTimestamp, 10)) ? minTimestamp : parseInt(minTimestamp, 10))
|
|
1057
|
+
: minTimestamp;
|
|
1058
|
+
}
|
|
1059
|
+
if (maxTimestamp != null) {
|
|
1060
|
+
instance.updatedAt = typeof maxTimestamp === 'string' && maxTimestamp.includes('T')
|
|
1061
|
+
? new Date(maxTimestamp).getTime()
|
|
1062
|
+
: typeof maxTimestamp === 'string'
|
|
1063
|
+
? (isNaN(parseInt(maxTimestamp, 10)) ? maxTimestamp : parseInt(maxTimestamp, 10))
|
|
1064
|
+
: maxTimestamp;
|
|
1065
|
+
}
|
|
1066
|
+
}
|
|
1067
|
+
|
|
713
1068
|
public static async assignValuesToInstance(perspective: PerspectiveProxy, instance: Ad4mModel, values: ValueTuple[]) {
|
|
714
1069
|
// Map properties to object
|
|
715
1070
|
const propsObject = Object.fromEntries(
|
|
@@ -750,7 +1105,8 @@ export class Ad4mModel {
|
|
|
750
1105
|
}
|
|
751
1106
|
}
|
|
752
1107
|
// Apply transform function if it exists
|
|
753
|
-
const
|
|
1108
|
+
const propsMeta = getPropertiesMetadata(instance.constructor);
|
|
1109
|
+
const transform = propsMeta[name]?.transform;
|
|
754
1110
|
if (transform && typeof transform === "function") {
|
|
755
1111
|
finalValue = transform(finalValue);
|
|
756
1112
|
}
|
|
@@ -781,203 +1137,230 @@ export class Ad4mModel {
|
|
|
781
1137
|
Object.assign(instance, writableProps);
|
|
782
1138
|
}
|
|
783
1139
|
|
|
784
|
-
|
|
785
|
-
|
|
1140
|
+
// ──────────────────────────────────────────────────────────
|
|
1141
|
+
// Snapshot / dirty tracking
|
|
1142
|
+
// ──────────────────────────────────────────────────────────
|
|
1143
|
+
|
|
1144
|
+
/**
|
|
1145
|
+
* Captures a shallow snapshot of the instance's current property and
|
|
1146
|
+
* relation values. Called automatically after hydration (`get()`,
|
|
1147
|
+
* query results). The snapshot is used by `isDirty()`,
|
|
1148
|
+
* `changedFields()`, and by `update()` to skip unchanged fields.
|
|
1149
|
+
* @private
|
|
1150
|
+
*/
|
|
1151
|
+
/**
|
|
1152
|
+
* Normalize a value for snapshot storage.
|
|
1153
|
+
* Arrays of model instances are reduced to their `.id` strings so that
|
|
1154
|
+
* dirty-tracking compares stable identifiers instead of object references.
|
|
1155
|
+
*/
|
|
1156
|
+
private static normalizeValue(value: any): any {
|
|
1157
|
+
if (Array.isArray(value)) {
|
|
1158
|
+
return value.map((v: any) =>
|
|
1159
|
+
v && typeof v === 'object' && typeof v.id === 'string' ? v.id : v,
|
|
1160
|
+
);
|
|
1161
|
+
}
|
|
1162
|
+
return value;
|
|
1163
|
+
}
|
|
1164
|
+
|
|
1165
|
+
/**
|
|
1166
|
+
* @param includedRelations Controls which relation fields are recorded
|
|
1167
|
+
* in the snapshot for dirty-tracking:
|
|
1168
|
+
* • `undefined` (default) — snapshot ALL relations (used by `.get()`,
|
|
1169
|
+
* `.create()`, `.save()` etc. where full hydration has occurred).
|
|
1170
|
+
* • `IncludeMap` object (e.g. `{ views: true }`) — only snapshot the
|
|
1171
|
+
* relations named in the map. Fields not listed are omitted from
|
|
1172
|
+
* the snapshot so that `changedFields()` ignores them.
|
|
1173
|
+
* • `null` / empty object — skip ALL relations (used by bare
|
|
1174
|
+
* subscriptions that don't eagerly load relations).
|
|
1175
|
+
*/
|
|
1176
|
+
private takeSnapshot(includedRelations?: Record<string, any> | null): void {
|
|
1177
|
+
const ctor = this.constructor as typeof Ad4mModel;
|
|
1178
|
+
const metadata = ctor.getModelMetadata();
|
|
1179
|
+
const snap: Record<string, any> = {};
|
|
1180
|
+
|
|
1181
|
+
// Always snapshot properties
|
|
1182
|
+
for (const propName of Object.keys(metadata.properties)) {
|
|
1183
|
+
const val = (this as any)[propName];
|
|
1184
|
+
snap[propName] = Ad4mModel.normalizeValue(
|
|
1185
|
+
Array.isArray(val) ? [...val] : val,
|
|
1186
|
+
);
|
|
1187
|
+
}
|
|
1188
|
+
|
|
1189
|
+
// Snapshot relations only when appropriate:
|
|
1190
|
+
// undefined → all relations (backward compat)
|
|
1191
|
+
// IncludeMap → only the keys present in the map
|
|
1192
|
+
// null / {} → none
|
|
1193
|
+
if (includedRelations === undefined) {
|
|
1194
|
+
// Full snapshot — e.g. after getData() / create()
|
|
1195
|
+
for (const relName of Object.keys(metadata.relations)) {
|
|
1196
|
+
const val = (this as any)[relName];
|
|
1197
|
+
snap[relName] = Ad4mModel.normalizeValue(
|
|
1198
|
+
Array.isArray(val) ? [...val] : val,
|
|
1199
|
+
);
|
|
1200
|
+
}
|
|
1201
|
+
} else if (includedRelations && Object.keys(includedRelations).length > 0) {
|
|
1202
|
+
// Partial snapshot — only the explicitly included relations
|
|
1203
|
+
for (const relName of Object.keys(includedRelations)) {
|
|
1204
|
+
if (relName in metadata.relations) {
|
|
1205
|
+
const val = (this as any)[relName];
|
|
1206
|
+
snap[relName] = Ad4mModel.normalizeValue(
|
|
1207
|
+
Array.isArray(val) ? [...val] : val,
|
|
1208
|
+
);
|
|
1209
|
+
}
|
|
1210
|
+
}
|
|
1211
|
+
}
|
|
1212
|
+
// else: null or empty object → skip all relations
|
|
1213
|
+
|
|
1214
|
+
this._snapshot = snap;
|
|
1215
|
+
}
|
|
1216
|
+
|
|
1217
|
+
/**
|
|
1218
|
+
* Returns `true` if any tracked property or relation has changed
|
|
1219
|
+
* since the last hydration (or since `takeSnapshot()` was last called).
|
|
1220
|
+
*
|
|
1221
|
+
* Always returns `true` if no snapshot exists (e.g. a freshly
|
|
1222
|
+
* constructed instance that hasn't been fetched yet).
|
|
1223
|
+
*
|
|
1224
|
+
* @example
|
|
1225
|
+
* ```typescript
|
|
1226
|
+
* const recipe = await Recipe.create(perspective, { name: "Pasta" });
|
|
1227
|
+
* recipe.isDirty(); // false — just hydrated
|
|
1228
|
+
* recipe.name = "Risotto";
|
|
1229
|
+
* recipe.isDirty(); // true
|
|
1230
|
+
* ```
|
|
1231
|
+
*/
|
|
1232
|
+
isDirty(): boolean {
|
|
1233
|
+
if (!this._snapshot) return true;
|
|
1234
|
+
return this.changedFields().length > 0;
|
|
1235
|
+
}
|
|
1236
|
+
|
|
1237
|
+
/**
|
|
1238
|
+
* Returns the names of properties/relations that differ from the
|
|
1239
|
+
* snapshot taken at the last hydration.
|
|
1240
|
+
*
|
|
1241
|
+
* Returns **all** field names if no snapshot exists.
|
|
1242
|
+
*
|
|
1243
|
+
* @example
|
|
1244
|
+
* ```typescript
|
|
1245
|
+
* recipe.name = "New Name";
|
|
1246
|
+
* recipe.changedFields(); // ["name"]
|
|
1247
|
+
* ```
|
|
1248
|
+
*/
|
|
1249
|
+
changedFields(): string[] {
|
|
1250
|
+
const ctor = this.constructor as typeof Ad4mModel;
|
|
1251
|
+
const metadata = ctor.getModelMetadata();
|
|
1252
|
+
|
|
1253
|
+
if (!this._snapshot) {
|
|
1254
|
+
return [
|
|
1255
|
+
...Object.keys(metadata.properties),
|
|
1256
|
+
...Object.keys(metadata.relations),
|
|
1257
|
+
];
|
|
1258
|
+
}
|
|
1259
|
+
|
|
1260
|
+
const changed: string[] = [];
|
|
1261
|
+
const allFields = [
|
|
1262
|
+
...Object.keys(metadata.properties),
|
|
1263
|
+
...Object.keys(metadata.relations),
|
|
1264
|
+
];
|
|
1265
|
+
|
|
1266
|
+
for (const field of allFields) {
|
|
1267
|
+
// Skip fields that were not recorded in the snapshot (e.g. relation
|
|
1268
|
+
// fields omitted because the originating query had no `include`).
|
|
1269
|
+
// Without this guard, a relation populated by hydrateFromLinks with
|
|
1270
|
+
// raw string IDs would appear "dirty" against a missing snapshot
|
|
1271
|
+
// entry and trigger an unnecessary (and potentially destructive)
|
|
1272
|
+
// setRelationValues call during innerUpdate.
|
|
1273
|
+
if (!(field in this._snapshot)) continue;
|
|
1274
|
+
|
|
1275
|
+
const current = Ad4mModel.normalizeValue((this as any)[field]);
|
|
1276
|
+
const original = this._snapshot[field];
|
|
1277
|
+
|
|
1278
|
+
if (Array.isArray(current) || Array.isArray(original)) {
|
|
1279
|
+
// Order-insensitive comparison (sorted) so reordering alone
|
|
1280
|
+
// doesn't mark a relation as dirty.
|
|
1281
|
+
const a = Array.isArray(current) ? [...current].sort() : [];
|
|
1282
|
+
const b = Array.isArray(original) ? [...original].sort() : [];
|
|
1283
|
+
if (a.length !== b.length || a.some((v: any, i: number) => v !== b[i])) {
|
|
1284
|
+
changed.push(field);
|
|
1285
|
+
}
|
|
1286
|
+
} else if (current !== original) {
|
|
1287
|
+
changed.push(field);
|
|
1288
|
+
}
|
|
1289
|
+
}
|
|
1290
|
+
return changed;
|
|
1291
|
+
}
|
|
1292
|
+
|
|
1293
|
+
private async getData(opts?: GetOptions) {
|
|
1294
|
+
// Builds an object with the author, timestamp, all properties, & all relations on the Ad4mModel and saves it to the instance
|
|
786
1295
|
// Use SurrealDB for data queries
|
|
787
1296
|
try {
|
|
788
1297
|
const ctor = this.constructor as typeof Ad4mModel;
|
|
789
1298
|
const metadata = ctor.getModelMetadata();
|
|
790
1299
|
|
|
791
1300
|
// Query for all links from this specific node (base expression)
|
|
792
|
-
|
|
793
|
-
const safeBaseExpression = ctor.formatSurrealValue(this.#baseExpression);
|
|
794
|
-
// Note: We use ORDER BY timestamp ASC because:
|
|
795
|
-
// - For collections: we want chronological order (oldest to newest)
|
|
796
|
-
// - For properties: we select the LAST element to get "latest wins" semantics
|
|
1301
|
+
const safeBaseExpression = ctor.formatSurrealValue(this._baseExpression);
|
|
797
1302
|
const linksQuery = `
|
|
798
1303
|
SELECT id, predicate, out.uri AS target, author, timestamp
|
|
799
1304
|
FROM link
|
|
800
1305
|
WHERE in.uri = ${safeBaseExpression}
|
|
801
1306
|
ORDER BY timestamp ASC
|
|
802
1307
|
`;
|
|
803
|
-
const links = await this
|
|
1308
|
+
const links = await this._perspective.querySurrealDB(linksQuery);
|
|
804
1309
|
|
|
805
1310
|
if (links && links.length > 0) {
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
// Process properties (skip those with custom getter)
|
|
812
|
-
for (const [propName, propMeta] of Object.entries(metadata.properties)) {
|
|
813
|
-
if (propMeta.getter) continue; // Handle via custom getter evaluation
|
|
814
|
-
const matching = links.filter((l: any) => l.predicate === propMeta.predicate);
|
|
815
|
-
if (matching.length > 0) {
|
|
816
|
-
// "Latest wins" semantics: select the last element since links are ordered ASC.
|
|
817
|
-
// The last element has the most recent timestamp and represents the current property value.
|
|
818
|
-
const link = matching[matching.length - 1];
|
|
819
|
-
let value = link.target;
|
|
820
|
-
|
|
821
|
-
// Track timestamps/authors for createdAt and updatedAt
|
|
822
|
-
if (link.timestamp) {
|
|
823
|
-
if (!minTimestamp || link.timestamp < minTimestamp) {
|
|
824
|
-
minTimestamp = link.timestamp;
|
|
825
|
-
originalAuthor = link.author;
|
|
826
|
-
}
|
|
827
|
-
if (!maxTimestamp || link.timestamp > maxTimestamp) {
|
|
828
|
-
maxTimestamp = link.timestamp;
|
|
829
|
-
latestAuthor = link.author;
|
|
830
|
-
}
|
|
831
|
-
}
|
|
832
|
-
|
|
833
|
-
// Handle resolveLanguage
|
|
834
|
-
if (propMeta.resolveLanguage && propMeta.resolveLanguage !== 'literal') {
|
|
835
|
-
try {
|
|
836
|
-
const expression = await this.#perspective.getExpression(value);
|
|
837
|
-
if (expression) {
|
|
838
|
-
try {
|
|
839
|
-
value = JSON.parse(expression.data);
|
|
840
|
-
} catch {
|
|
841
|
-
value = expression.data;
|
|
842
|
-
}
|
|
843
|
-
}
|
|
844
|
-
} catch (e) {
|
|
845
|
-
console.warn(`Failed to resolve expression for ${propName}:`, e);
|
|
846
|
-
}
|
|
847
|
-
} else if (propMeta.resolveLanguage === 'literal' && typeof value === 'string' && value.startsWith('literal://')) {
|
|
848
|
-
// Only parse literal URIs when resolveLanguage is explicitly 'literal'.
|
|
849
|
-
// Without this guard, properties pointing to baseExpressions of other models
|
|
850
|
-
// (which may be literal:// strings) would get unwrapped, breaking link URI validation.
|
|
851
|
-
try {
|
|
852
|
-
const parsed = Literal.fromUrl(value).get();
|
|
853
|
-
value = parsed.data !== undefined ? parsed.data : parsed;
|
|
854
|
-
} catch (e) {
|
|
855
|
-
// Keep original value
|
|
856
|
-
}
|
|
857
|
-
}
|
|
858
|
-
|
|
859
|
-
// Apply transform if exists
|
|
860
|
-
if (propMeta.transform && typeof propMeta.transform === 'function') {
|
|
861
|
-
value = propMeta.transform(value);
|
|
862
|
-
}
|
|
863
|
-
|
|
864
|
-
(this as any)[propName] = value;
|
|
865
|
-
}
|
|
866
|
-
}
|
|
867
|
-
|
|
868
|
-
// Process collections (skip those with custom getter)
|
|
869
|
-
for (const [collName, collMeta] of Object.entries(metadata.collections)) {
|
|
870
|
-
if (collMeta.getter) continue; // Handle via custom getter evaluation
|
|
871
|
-
const matching = links.filter((l: any) => l.predicate === collMeta.predicate);
|
|
872
|
-
// Collections preserve chronological order: links are sorted ASC by timestamp,
|
|
873
|
-
// so the collection reflects the order in which items were added (oldest to newest).
|
|
874
|
-
let values = matching.map((l: any) => l.target);
|
|
875
|
-
|
|
876
|
-
// Apply where.condition filtering if present
|
|
877
|
-
if (collMeta.where?.condition && values.length > 0) {
|
|
878
|
-
try {
|
|
879
|
-
// Filter values by evaluating condition for each value
|
|
880
|
-
const filteredValues: string[] = [];
|
|
881
|
-
|
|
882
|
-
for (const value of values) {
|
|
883
|
-
let condition = collMeta.where.condition
|
|
884
|
-
.replace(/\$perspective/g, `'${this.#perspective.uuid}'`)
|
|
885
|
-
.replace(/\$base/g, `'${this.#baseExpression}'`)
|
|
886
|
-
.replace(/Target/g, `'${value.replace(/'/g, "\\'")}'`);
|
|
887
|
-
|
|
888
|
-
// If condition starts with WHERE, wrap it in array length check pattern
|
|
889
|
-
// Using array::len() to properly count matching links
|
|
890
|
-
if (condition.trim().startsWith('WHERE')) {
|
|
891
|
-
condition = `array::len(SELECT * FROM link ${condition}) > 0`;
|
|
892
|
-
}
|
|
893
|
-
|
|
894
|
-
const filterQuery = `RETURN ${condition}`;
|
|
895
|
-
const result = await this.#perspective.querySurrealDB(filterQuery);
|
|
896
|
-
|
|
897
|
-
// RETURN can return the value directly or in an array
|
|
898
|
-
const isTrue = result === true || (Array.isArray(result) && result.length > 0 && result[0] === true);
|
|
899
|
-
if (isTrue) {
|
|
900
|
-
filteredValues.push(value);
|
|
901
|
-
}
|
|
902
|
-
}
|
|
903
|
-
|
|
904
|
-
values = filteredValues;
|
|
905
|
-
} catch (error) {
|
|
906
|
-
console.warn(`Failed to apply condition filter for ${collName}:`, error);
|
|
907
|
-
// Keep unfiltered values on error
|
|
908
|
-
}
|
|
909
|
-
}
|
|
910
|
-
|
|
911
|
-
// Apply where.isInstance filtering if present
|
|
912
|
-
if (collMeta.where?.isInstance && values.length > 0) {
|
|
913
|
-
try {
|
|
914
|
-
const className = typeof collMeta.where.isInstance === 'string'
|
|
915
|
-
? collMeta.where.isInstance
|
|
916
|
-
: collMeta.where.isInstance.name;
|
|
917
|
-
|
|
918
|
-
const filterMetadata = await this.#perspective.getSubjectClassMetadataFromSDNA(className);
|
|
919
|
-
if (filterMetadata) {
|
|
920
|
-
values = await this.#perspective.batchCheckSubjectInstances(values, filterMetadata);
|
|
921
|
-
}
|
|
922
|
-
} catch (error) {
|
|
923
|
-
// Keep unfiltered values on error
|
|
924
|
-
}
|
|
925
|
-
}
|
|
926
|
-
|
|
927
|
-
(this as any)[collName] = values;
|
|
928
|
-
}
|
|
1311
|
+
// Core hydration: properties (latest-wins), relations, timestamps/author
|
|
1312
|
+
const requestedProperties = opts?.properties && opts.properties.length > 0 ? opts.properties : undefined;
|
|
1313
|
+
await ctor.hydrateFromLinks(this, links, metadata, this._perspective, requestedProperties);
|
|
1314
|
+
}
|
|
929
1315
|
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
if (
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
1316
|
+
// Populate reverse relation fields (belongsToOne / belongsToMany) as string IDs.
|
|
1317
|
+
const allRelsMeta = getRelationsMetadata(ctor as any);
|
|
1318
|
+
const requestedProps = opts?.properties && opts.properties.length > 0 ? new Set(opts.properties) : null;
|
|
1319
|
+
for (const [relName, relMeta] of Object.entries(allRelsMeta)) {
|
|
1320
|
+
if (relMeta.kind !== 'belongsToOne' && relMeta.kind !== 'belongsToMany') continue;
|
|
1321
|
+
if (requestedProps && !requestedProps.has(relName)) continue;
|
|
1322
|
+
const reverseLinks = await this._perspective.get(
|
|
1323
|
+
new LinkQuery({ predicate: relMeta.predicate, target: this._baseExpression })
|
|
1324
|
+
);
|
|
1325
|
+
const sourceIds = reverseLinks
|
|
1326
|
+
.filter((l) => l.data.target === this._baseExpression)
|
|
1327
|
+
.map((l) => l.data.source);
|
|
1328
|
+
if (relMeta.kind === 'belongsToOne') {
|
|
1329
|
+
(this as any)[relName] = sourceIds.length > 0 ? sourceIds[sourceIds.length - 1] : null;
|
|
1330
|
+
} else {
|
|
1331
|
+
(this as any)[relName] = sourceIds;
|
|
939
1332
|
}
|
|
940
1333
|
}
|
|
941
1334
|
|
|
942
1335
|
// Evaluate SurrealQL getters
|
|
943
|
-
await ctor.evaluateCustomGettersForInstance(this, this
|
|
944
|
-
|
|
945
|
-
//
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
if (collMeta.getter && collMeta.where?.isInstance && (this as any)[collName]?.length > 0) {
|
|
949
|
-
try {
|
|
950
|
-
const className = typeof collMeta.where.isInstance === 'string'
|
|
951
|
-
? collMeta.where.isInstance
|
|
952
|
-
: collMeta.where.isInstance.name;
|
|
953
|
-
|
|
954
|
-
const filterMetadata = await this.#perspective.getSubjectClassMetadataFromSDNA(className);
|
|
955
|
-
if (filterMetadata) {
|
|
956
|
-
const filtered = await this.#perspective.batchCheckSubjectInstances((this as any)[collName], filterMetadata);
|
|
957
|
-
(this as any)[collName] = filtered;
|
|
958
|
-
}
|
|
959
|
-
} catch (error) {
|
|
960
|
-
// Keep unfiltered values on error
|
|
961
|
-
}
|
|
962
|
-
}
|
|
1336
|
+
await ctor.evaluateCustomGettersForInstance(this, this._perspective, metadata);
|
|
1337
|
+
|
|
1338
|
+
// Eager-load relations if requested
|
|
1339
|
+
if (opts?.include) {
|
|
1340
|
+
await ctor.hydrateRelations([this], this._perspective, opts.include);
|
|
963
1341
|
}
|
|
964
1342
|
} catch (e) {
|
|
965
|
-
console.error(`SurrealDB getData also failed for ${this
|
|
1343
|
+
console.error(`SurrealDB getData also failed for ${this._baseExpression}:`, e);
|
|
966
1344
|
}
|
|
967
1345
|
|
|
1346
|
+
this.takeSnapshot();
|
|
968
1347
|
return this;
|
|
969
1348
|
}
|
|
970
1349
|
|
|
971
1350
|
// Todo: Only return AllInstances (InstancesWithOffset, SortedInstances, & UnsortedInstances not required)
|
|
972
1351
|
public static async queryToProlog(perspective: PerspectiveProxy, query: Query, modelClassName?: string | null) {
|
|
973
|
-
const {
|
|
1352
|
+
const { properties, where, order, offset, limit, count } = query;
|
|
974
1353
|
const className = modelClassName || (await this.getClassName(perspective));
|
|
975
1354
|
|
|
1355
|
+
// Resolve parent predicate from model metadata if needed
|
|
1356
|
+
const resolvedParentPredicate = query.parent
|
|
1357
|
+
? resolveParentPredicate(query.parent, this)
|
|
1358
|
+
: undefined;
|
|
1359
|
+
|
|
976
1360
|
const instanceQueries = [
|
|
977
1361
|
buildAuthorAndTimestampQuery(),
|
|
978
|
-
|
|
1362
|
+
buildParentQuery(query.parent, resolvedParentPredicate),
|
|
979
1363
|
buildPropertiesQuery(properties),
|
|
980
|
-
buildCollectionsQuery(collections),
|
|
981
1364
|
buildWhereQuery(where),
|
|
982
1365
|
];
|
|
983
1366
|
|
|
@@ -996,7 +1379,7 @@ export class Ad4mModel {
|
|
|
996
1379
|
}
|
|
997
1380
|
|
|
998
1381
|
/**
|
|
999
|
-
* Evaluates custom SurrealQL getters for properties and
|
|
1382
|
+
* Evaluates custom SurrealQL getters for properties and relations on a specific instance.
|
|
1000
1383
|
* @private
|
|
1001
1384
|
*/
|
|
1002
1385
|
private static async evaluateCustomGettersForInstance(
|
|
@@ -1004,7 +1387,7 @@ export class Ad4mModel {
|
|
|
1004
1387
|
perspective: PerspectiveProxy,
|
|
1005
1388
|
metadata: any
|
|
1006
1389
|
) {
|
|
1007
|
-
const safeBaseExpression = this.formatSurrealValue(instance.
|
|
1390
|
+
const safeBaseExpression = this.formatSurrealValue(instance.id);
|
|
1008
1391
|
|
|
1009
1392
|
// Evaluate property getters
|
|
1010
1393
|
for (const [propName, propMeta] of Object.entries(metadata.properties)) {
|
|
@@ -1025,27 +1408,273 @@ export class Ad4mModel {
|
|
|
1025
1408
|
}
|
|
1026
1409
|
}
|
|
1027
1410
|
|
|
1028
|
-
// Evaluate
|
|
1029
|
-
for (const [
|
|
1030
|
-
if ((
|
|
1411
|
+
// Evaluate relation getters
|
|
1412
|
+
for (const [relName, relMeta] of Object.entries(metadata.relations)) {
|
|
1413
|
+
if ((relMeta as any).getter) {
|
|
1031
1414
|
try {
|
|
1032
1415
|
// Replace 'Base' placeholder with actual base expression
|
|
1033
|
-
const query = (
|
|
1416
|
+
const query = (relMeta as any).getter.replace(/Base/g, safeBaseExpression);
|
|
1034
1417
|
// Query from node table to have graph traversal context
|
|
1035
1418
|
const result = await perspective.querySurrealDB(
|
|
1036
1419
|
`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`
|
|
1037
1420
|
);
|
|
1038
1421
|
if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
|
|
1039
|
-
// Filter out 'None' from
|
|
1422
|
+
// Filter out 'None' from relation results
|
|
1040
1423
|
const value = result[0].value;
|
|
1041
|
-
instance[
|
|
1424
|
+
instance[relName] = Array.isArray(value)
|
|
1042
1425
|
? value.filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None')
|
|
1043
1426
|
: value;
|
|
1044
1427
|
}
|
|
1045
1428
|
} catch (error) {
|
|
1046
|
-
console.warn(`Failed to evaluate getter for ${
|
|
1429
|
+
console.warn(`Failed to evaluate getter for ${relName}:`, error);
|
|
1430
|
+
}
|
|
1431
|
+
}
|
|
1432
|
+
}
|
|
1433
|
+
}
|
|
1434
|
+
|
|
1435
|
+
/**
|
|
1436
|
+
* Hydrates relation fields on instances according to the provided IncludeMap.
|
|
1437
|
+
*
|
|
1438
|
+
* For each relation listed in `includeMap`, the raw expression-URI strings
|
|
1439
|
+
* stored on the instance are replaced with fully-hydrated model instances
|
|
1440
|
+
* (fetched via the relation's `target()` class). Nested IncludeMaps are
|
|
1441
|
+
* supported for multi-level eager loading.
|
|
1442
|
+
*
|
|
1443
|
+
* @param instances - The instances whose relations should be hydrated
|
|
1444
|
+
* @param perspective - The perspective to fetch related instances from
|
|
1445
|
+
* @param includeMap - Describes which relations to hydrate
|
|
1446
|
+
* @private
|
|
1447
|
+
*/
|
|
1448
|
+
private static async hydrateRelations<T extends Ad4mModel>(
|
|
1449
|
+
instances: T[],
|
|
1450
|
+
perspective: PerspectiveProxy,
|
|
1451
|
+
includeMap: IncludeMap | undefined,
|
|
1452
|
+
): Promise<void> {
|
|
1453
|
+
if (!includeMap || Object.keys(includeMap).length === 0) return;
|
|
1454
|
+
|
|
1455
|
+
const relMeta = getRelationsMetadata(this);
|
|
1456
|
+
|
|
1457
|
+
for (const [relName, includeValue] of Object.entries(includeMap)) {
|
|
1458
|
+
const meta: RelationMetadataEntry | undefined = relMeta[relName];
|
|
1459
|
+
if (!meta) {
|
|
1460
|
+
console.warn(`include: relation "${relName}" not found in metadata, skipping`);
|
|
1461
|
+
continue;
|
|
1462
|
+
}
|
|
1463
|
+
|
|
1464
|
+
const TargetClass = meta.target() as unknown as typeof Ad4mModel;
|
|
1465
|
+
|
|
1466
|
+
// Determine if a RelationSubQuery was supplied (object) vs a plain `true`
|
|
1467
|
+
const subQuery: RelationSubQuery | undefined =
|
|
1468
|
+
typeof includeValue === 'object' && includeValue !== null
|
|
1469
|
+
? (includeValue as RelationSubQuery)
|
|
1470
|
+
: undefined;
|
|
1471
|
+
const nestedInclude: IncludeMap | undefined = subQuery?.include;
|
|
1472
|
+
|
|
1473
|
+
// ── Reverse relations (belongsToOne / belongsToMany) ──────────────────
|
|
1474
|
+
// The link goes target→instance, so we query backwards:
|
|
1475
|
+
// predicate = meta.predicate, target = inst.id → source is the related id
|
|
1476
|
+
if (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') {
|
|
1477
|
+
// Per-instance reverse lookup (can't batch easily across instances)
|
|
1478
|
+
for (const inst of instances) {
|
|
1479
|
+
const reverseLinks = await perspective.get(
|
|
1480
|
+
new LinkQuery({ predicate: meta.predicate, target: inst.id })
|
|
1481
|
+
);
|
|
1482
|
+
// Defensive filter: perspective.get may return extra results; ensure
|
|
1483
|
+
// we only use links that genuinely point to this instance.
|
|
1484
|
+
const sourceIds = reverseLinks
|
|
1485
|
+
.filter(l => l.data.target === inst.id)
|
|
1486
|
+
.map(l => l.data.source);
|
|
1487
|
+
|
|
1488
|
+
if (meta.kind === 'belongsToOne') {
|
|
1489
|
+
if (sourceIds.length === 0) {
|
|
1490
|
+
(inst as any)[relName] = null;
|
|
1491
|
+
continue;
|
|
1492
|
+
}
|
|
1493
|
+
const sourceId = sourceIds[sourceIds.length - 1]; // latest-wins
|
|
1494
|
+
try {
|
|
1495
|
+
const related = new TargetClass(perspective, sourceId);
|
|
1496
|
+
await related.get();
|
|
1497
|
+
(inst as any)[relName] = related;
|
|
1498
|
+
} catch {
|
|
1499
|
+
(inst as any)[relName] = null;
|
|
1500
|
+
}
|
|
1501
|
+
} else {
|
|
1502
|
+
// belongsToMany — return array of hydrated instances
|
|
1503
|
+
let hydrated: Ad4mModel[] = [];
|
|
1504
|
+
|
|
1505
|
+
// If there's a where/order sub-query, delegate to findAll for filtering
|
|
1506
|
+
if (subQuery && (subQuery.where || subQuery.order || subQuery.properties)) {
|
|
1507
|
+
const whereWithIds: Record<string, any> = {
|
|
1508
|
+
id: sourceIds,
|
|
1509
|
+
...(subQuery.where ?? {}),
|
|
1510
|
+
};
|
|
1511
|
+
hydrated = await TargetClass.findAll(perspective, {
|
|
1512
|
+
where: whereWithIds as any,
|
|
1513
|
+
...(subQuery.order && { order: subQuery.order as any }),
|
|
1514
|
+
...(subQuery.properties && { properties: subQuery.properties }),
|
|
1515
|
+
});
|
|
1516
|
+
} else {
|
|
1517
|
+
await Promise.all(sourceIds.map(async (sid) => {
|
|
1518
|
+
try {
|
|
1519
|
+
const related = new TargetClass(perspective, sid);
|
|
1520
|
+
await related.get(
|
|
1521
|
+
subQuery?.properties ? { properties: subQuery.properties } : undefined
|
|
1522
|
+
);
|
|
1523
|
+
hydrated.push(related);
|
|
1524
|
+
} catch { /* skip */ }
|
|
1525
|
+
}));
|
|
1526
|
+
}
|
|
1527
|
+
|
|
1528
|
+
// Apply order (client-side, if not already handled by findAll above)
|
|
1529
|
+
if (subQuery?.order && !(subQuery.where || subQuery.properties)) {
|
|
1530
|
+
const orderEntries = Object.entries(subQuery.order);
|
|
1531
|
+
hydrated = hydrated.sort((a, b) => {
|
|
1532
|
+
for (const [field, dir] of orderEntries) {
|
|
1533
|
+
const av = String((a as any)[field] ?? '');
|
|
1534
|
+
const bv = String((b as any)[field] ?? '');
|
|
1535
|
+
const diff = av.localeCompare(bv);
|
|
1536
|
+
if (diff !== 0) return dir === 'DESC' ? -diff : diff;
|
|
1537
|
+
}
|
|
1538
|
+
return 0;
|
|
1539
|
+
});
|
|
1540
|
+
}
|
|
1541
|
+
|
|
1542
|
+
// Apply offset and limit
|
|
1543
|
+
if (subQuery?.offset != null || subQuery?.limit != null) {
|
|
1544
|
+
const start = subQuery.offset ?? 0;
|
|
1545
|
+
const end = subQuery.limit != null ? start + subQuery.limit : undefined;
|
|
1546
|
+
hydrated = hydrated.slice(start, end);
|
|
1547
|
+
}
|
|
1548
|
+
|
|
1549
|
+
(inst as any)[relName] = hydrated;
|
|
1550
|
+
|
|
1551
|
+
// Recurse for nested includes
|
|
1552
|
+
if (nestedInclude && hydrated.length > 0) {
|
|
1553
|
+
await TargetClass.hydrateRelations(hydrated, perspective, nestedInclude);
|
|
1554
|
+
}
|
|
1555
|
+
}
|
|
1556
|
+
}
|
|
1557
|
+
continue; // skip the forward-relation path below
|
|
1558
|
+
}
|
|
1559
|
+
|
|
1560
|
+
// ── Forward relations (hasMany / hasOne) ──────────────────────────────
|
|
1561
|
+
// Collect all unique URIs across all instances for batch-friendly lookup.
|
|
1562
|
+
// IMPORTANT: We cache each instance's raw value NOW (before the async
|
|
1563
|
+
// findAll) so that concurrent getData() calls on the same instance can't
|
|
1564
|
+
// overwrite the relation field between the uriSet relation and the
|
|
1565
|
+
// post-await assignment loop. Without this cache, a concurrent call
|
|
1566
|
+
// can replace the raw URI strings with hydrated model objects, causing
|
|
1567
|
+
// the `typeof v === 'string'` check to fail and the array to end up empty.
|
|
1568
|
+
const uriSet = new Set<string>();
|
|
1569
|
+
const rawCache = new Map<T, any>();
|
|
1570
|
+
for (const inst of instances) {
|
|
1571
|
+
const raw = (inst as any)[relName];
|
|
1572
|
+
rawCache.set(inst, Array.isArray(raw) ? [...raw] : raw);
|
|
1573
|
+
if (raw == null) continue;
|
|
1574
|
+
if (Array.isArray(raw)) {
|
|
1575
|
+
for (const v of raw) {
|
|
1576
|
+
if (typeof v === 'string') uriSet.add(v);
|
|
1577
|
+
// Handle already-hydrated instances (from a concurrent call)
|
|
1578
|
+
else if (v && typeof v === 'object' && typeof v.id === 'string') uriSet.add(v.id);
|
|
1579
|
+
}
|
|
1580
|
+
} else if (typeof raw === 'string') {
|
|
1581
|
+
uriSet.add(raw);
|
|
1582
|
+
} else if (raw && typeof raw === 'object' && typeof raw.id === 'string') {
|
|
1583
|
+
uriSet.add(raw.id);
|
|
1584
|
+
}
|
|
1585
|
+
}
|
|
1586
|
+
|
|
1587
|
+
if (uriSet.size === 0) continue;
|
|
1588
|
+
|
|
1589
|
+
// Hydrate related instances using findAll to ensure conformance checking.
|
|
1590
|
+
// findAll validates model membership via graph traversal (required predicates / flags),
|
|
1591
|
+
// so non-conforming linked URIs are silently dropped — matching the documented behaviour.
|
|
1592
|
+
const hydrated = new Map<string, Ad4mModel>();
|
|
1593
|
+
|
|
1594
|
+
const whereWithIds: Record<string, any> = {
|
|
1595
|
+
id: Array.from(uriSet),
|
|
1596
|
+
...(subQuery?.where ?? {}),
|
|
1597
|
+
};
|
|
1598
|
+
const fetchQuery: any = {
|
|
1599
|
+
where: whereWithIds,
|
|
1600
|
+
...(subQuery?.order && { order: subQuery.order }),
|
|
1601
|
+
...(subQuery?.properties && { properties: subQuery.properties }),
|
|
1602
|
+
};
|
|
1603
|
+
const results = await TargetClass.findAll(perspective, fetchQuery);
|
|
1604
|
+
for (const result of results) {
|
|
1605
|
+
hydrated.set(result.id, result);
|
|
1606
|
+
}
|
|
1607
|
+
|
|
1608
|
+
// Replace raw URIs with hydrated instances on each parent instance.
|
|
1609
|
+
// Use the cached raw values captured BEFORE the async findAll to avoid
|
|
1610
|
+
// the race condition where a concurrent getData() already replaced the
|
|
1611
|
+
// strings with hydrated objects.
|
|
1612
|
+
for (const inst of instances) {
|
|
1613
|
+
const raw = rawCache.get(inst);
|
|
1614
|
+
if (raw == null) continue;
|
|
1615
|
+
if (Array.isArray(raw)) {
|
|
1616
|
+
// Map URIs → instances; handle both raw strings and already-hydrated objects
|
|
1617
|
+
let resolved: Ad4mModel[] = raw
|
|
1618
|
+
.map((v: any) => {
|
|
1619
|
+
if (typeof v === 'string') {
|
|
1620
|
+
return hydrated.has(v) ? hydrated.get(v)! : null;
|
|
1621
|
+
}
|
|
1622
|
+
// Already a hydrated model instance (from a concurrent call)
|
|
1623
|
+
if (v && typeof v === 'object' && typeof v.id === 'string') {
|
|
1624
|
+
return hydrated.has(v.id) ? hydrated.get(v.id)! : v;
|
|
1625
|
+
}
|
|
1626
|
+
return null;
|
|
1627
|
+
})
|
|
1628
|
+
.filter((v): v is Ad4mModel => v !== null);
|
|
1629
|
+
|
|
1630
|
+
// Per-instance sort (client-side, after filtering)
|
|
1631
|
+
if (subQuery?.order) {
|
|
1632
|
+
const orderEntries = Object.entries(subQuery.order);
|
|
1633
|
+
resolved = resolved.sort((a, b) => {
|
|
1634
|
+
for (const [field, dir] of orderEntries) {
|
|
1635
|
+
const av = String((a as any)[field] ?? '');
|
|
1636
|
+
const bv = String((b as any)[field] ?? '');
|
|
1637
|
+
const diff = av.localeCompare(bv);
|
|
1638
|
+
if (diff !== 0) return dir === 'DESC' ? -diff : diff;
|
|
1639
|
+
}
|
|
1640
|
+
return 0;
|
|
1641
|
+
});
|
|
1642
|
+
}
|
|
1643
|
+
|
|
1644
|
+
// Per-instance limit / offset
|
|
1645
|
+
if (subQuery?.offset != null || subQuery?.limit != null) {
|
|
1646
|
+
const start = subQuery.offset ?? 0;
|
|
1647
|
+
const end =
|
|
1648
|
+
subQuery.limit != null ? start + subQuery.limit : undefined;
|
|
1649
|
+
resolved = resolved.slice(start, end);
|
|
1650
|
+
}
|
|
1651
|
+
|
|
1652
|
+
// Enforce maxCount guard — single-valued relations keep only the last item
|
|
1653
|
+
if (meta.maxCount === 1) {
|
|
1654
|
+
if (resolved.length > 1) {
|
|
1655
|
+
console.warn(
|
|
1656
|
+
`include: relation "${relName}" has maxCount 1 but ${resolved.length} values found; keeping the last`,
|
|
1657
|
+
);
|
|
1658
|
+
}
|
|
1659
|
+
(inst as any)[relName] = resolved.length > 0
|
|
1660
|
+
? resolved[resolved.length - 1]
|
|
1661
|
+
: null;
|
|
1662
|
+
} else {
|
|
1663
|
+
(inst as any)[relName] = resolved;
|
|
1664
|
+
}
|
|
1665
|
+
} else if (typeof raw === 'string' && hydrated.has(raw)) {
|
|
1666
|
+
(inst as any)[relName] = hydrated.get(raw);
|
|
1667
|
+
} else if (raw && typeof raw === 'object' && typeof raw.id === 'string') {
|
|
1668
|
+
// Already-hydrated object — look up refreshed version or keep as-is
|
|
1669
|
+
(inst as any)[relName] = hydrated.has(raw.id) ? hydrated.get(raw.id) : raw;
|
|
1047
1670
|
}
|
|
1048
1671
|
}
|
|
1672
|
+
|
|
1673
|
+
// Recurse for nested includes
|
|
1674
|
+
if (nestedInclude) {
|
|
1675
|
+
const hydratedInstances = Array.from(hydrated.values());
|
|
1676
|
+
await TargetClass.hydrateRelations(hydratedInstances, perspective, nestedInclude);
|
|
1677
|
+
}
|
|
1049
1678
|
}
|
|
1050
1679
|
}
|
|
1051
1680
|
|
|
@@ -1060,18 +1689,18 @@ export class Ad4mModel {
|
|
|
1060
1689
|
*
|
|
1061
1690
|
* The generated query uses a CTE (Common Table Expression) pattern:
|
|
1062
1691
|
* 1. First, identify candidate base expressions by filtering links based on where conditions
|
|
1063
|
-
* 2. Then, for each candidate base, resolve properties and
|
|
1692
|
+
* 2. Then, for each candidate base, resolve properties and relations via subqueries
|
|
1064
1693
|
* 3. Finally, apply ordering, pagination (LIMIT/START) at the SQL level
|
|
1065
1694
|
*
|
|
1066
1695
|
* Key architectural notes:
|
|
1067
1696
|
* - SurrealDB stores only raw links (source, predicate, target, author, timestamp)
|
|
1068
1697
|
* - No SDNA knowledge at the database level
|
|
1069
1698
|
* - Properties are resolved via subqueries that look for links with specific predicates
|
|
1070
|
-
* -
|
|
1699
|
+
* - Relations are similar but return multiple values instead of one
|
|
1071
1700
|
* - Special fields (base, author, timestamp) are accessed directly, not via subqueries
|
|
1072
1701
|
*
|
|
1073
1702
|
* @param perspective - The perspective to query (used for metadata extraction)
|
|
1074
|
-
* @param query - Query parameters (where, order, limit, offset, properties,
|
|
1703
|
+
* @param query - Query parameters (where, order, limit, offset, properties, relations)
|
|
1075
1704
|
* @returns Complete SurrealQL query string ready for execution
|
|
1076
1705
|
*
|
|
1077
1706
|
* @example
|
|
@@ -1087,54 +1716,82 @@ export class Ad4mModel {
|
|
|
1087
1716
|
*/
|
|
1088
1717
|
public static async queryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
|
|
1089
1718
|
const metadata = this.getModelMetadata();
|
|
1090
|
-
const {
|
|
1719
|
+
const { where, order, offset, limit } = query;
|
|
1091
1720
|
|
|
1092
1721
|
// Build list of graph traversal filters for required predicates
|
|
1093
1722
|
const graphTraversalFilters: string[] = [];
|
|
1094
1723
|
|
|
1095
|
-
// Add
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
// Use graph traversal: node must be target of has_child link from source
|
|
1724
|
+
// Add parent filter if specified (filter to nodes linked from a parent via a specific predicate)
|
|
1725
|
+
if (query.parent) {
|
|
1726
|
+
const parentPredicate = resolveParentPredicate(query.parent, this);
|
|
1099
1727
|
graphTraversalFilters.push(
|
|
1100
|
-
`count(<-link[WHERE
|
|
1728
|
+
`count(<-link[WHERE in.uri = ${this.formatSurrealValue(query.parent.id)} AND predicate = '${escapeSurrealString(parentPredicate)}']) > 0`
|
|
1101
1729
|
);
|
|
1102
1730
|
}
|
|
1103
1731
|
|
|
1104
1732
|
// Add filters for required properties
|
|
1105
1733
|
for (const [propName, propMeta] of Object.entries(metadata.properties)) {
|
|
1106
1734
|
if (propMeta.required) {
|
|
1735
|
+
// Skip properties with a getter — they are computed dynamically
|
|
1736
|
+
// and may not have a stored link with their predicate, so requiring their
|
|
1737
|
+
// presence would wrongly exclude valid model instances.
|
|
1738
|
+
if (propMeta.getter) continue;
|
|
1739
|
+
|
|
1107
1740
|
// For flag properties, also filter by the target value
|
|
1108
1741
|
if (propMeta.flag && propMeta.initial) {
|
|
1109
1742
|
graphTraversalFilters.push(
|
|
1110
|
-
`count(->link[WHERE
|
|
1743
|
+
`count(->link[WHERE predicate = '${escapeSurrealString(propMeta.predicate)}' AND out.uri = '${escapeSurrealString(propMeta.initial)}']) > 0`
|
|
1111
1744
|
);
|
|
1112
1745
|
} else {
|
|
1113
1746
|
graphTraversalFilters.push(
|
|
1114
|
-
`count(->link[WHERE
|
|
1747
|
+
`count(->link[WHERE predicate = '${escapeSurrealString(propMeta.predicate)}']) > 0`
|
|
1115
1748
|
);
|
|
1116
1749
|
}
|
|
1117
1750
|
}
|
|
1118
1751
|
}
|
|
1119
1752
|
|
|
1120
|
-
// If no required properties
|
|
1121
|
-
//
|
|
1753
|
+
// If no required properties produced filters, try properties with initial
|
|
1754
|
+
// values (e.g. @Flag or @Property with an explicit initial).
|
|
1122
1755
|
if (graphTraversalFilters.length === 0) {
|
|
1123
1756
|
for (const [propName, propMeta] of Object.entries(metadata.properties)) {
|
|
1124
1757
|
if (propMeta.initial) {
|
|
1125
|
-
// For flag properties, also filter by the target value
|
|
1126
1758
|
if (propMeta.flag) {
|
|
1127
1759
|
graphTraversalFilters.push(
|
|
1128
|
-
`count(->link[WHERE
|
|
1760
|
+
`count(->link[WHERE predicate = '${escapeSurrealString(propMeta.predicate)}' AND out.uri = '${escapeSurrealString(propMeta.initial)}']) > 0`
|
|
1129
1761
|
);
|
|
1130
1762
|
} else {
|
|
1131
1763
|
graphTraversalFilters.push(
|
|
1132
|
-
`count(->link[WHERE
|
|
1764
|
+
`count(->link[WHERE predicate = '${escapeSurrealString(propMeta.predicate)}']) > 0`
|
|
1133
1765
|
);
|
|
1134
1766
|
}
|
|
1135
|
-
break;
|
|
1767
|
+
break;
|
|
1768
|
+
}
|
|
1769
|
+
}
|
|
1770
|
+
}
|
|
1771
|
+
|
|
1772
|
+
// Still no filters → open-world structural matching.
|
|
1773
|
+
// Require the node to have at least one link whose predicate is declared
|
|
1774
|
+
// by this model (property OR relation). This prevents the query from
|
|
1775
|
+
// matching every node in the perspective.
|
|
1776
|
+
if (graphTraversalFilters.length === 0) {
|
|
1777
|
+
const structuralPredicates: string[] = [];
|
|
1778
|
+
for (const [, propMeta] of Object.entries(metadata.properties)) {
|
|
1779
|
+
if (propMeta.predicate) {
|
|
1780
|
+
structuralPredicates.push(`predicate = '${escapeSurrealString(propMeta.predicate)}'`);
|
|
1781
|
+
}
|
|
1782
|
+
}
|
|
1783
|
+
if (metadata.relations) {
|
|
1784
|
+
for (const [, relMeta] of Object.entries(metadata.relations)) {
|
|
1785
|
+
if (relMeta.predicate) {
|
|
1786
|
+
structuralPredicates.push(`predicate = '${escapeSurrealString(relMeta.predicate)}'`);
|
|
1787
|
+
}
|
|
1136
1788
|
}
|
|
1137
1789
|
}
|
|
1790
|
+
if (structuralPredicates.length > 0) {
|
|
1791
|
+
graphTraversalFilters.push(
|
|
1792
|
+
`count(->link[WHERE (${structuralPredicates.join(' OR ')})]) > 0`
|
|
1793
|
+
);
|
|
1794
|
+
}
|
|
1138
1795
|
}
|
|
1139
1796
|
|
|
1140
1797
|
// Build user WHERE clause filters using graph traversal
|
|
@@ -1151,18 +1808,21 @@ export class Ad4mModel {
|
|
|
1151
1808
|
whereConditions.push(userWhereClause);
|
|
1152
1809
|
}
|
|
1153
1810
|
|
|
1154
|
-
// Always ensure node has at least one link
|
|
1155
|
-
whereConditions.push(`count(->link
|
|
1811
|
+
// Always ensure node has at least one link (each perspective has its own isolated DB)
|
|
1812
|
+
whereConditions.push(`count(->link) > 0`);
|
|
1156
1813
|
|
|
1157
1814
|
// Build the query FROM node using direct graph traversal in WHERE
|
|
1158
1815
|
// This avoids slow subqueries and uses graph indexes for fast traversal
|
|
1816
|
+
// FETCH links expands the link record IDs into full record objects
|
|
1817
|
+
// (without FETCH, ->link returns only IDs like "link:abc123")
|
|
1159
1818
|
const fullQuery = `
|
|
1160
1819
|
SELECT
|
|
1161
1820
|
id AS source,
|
|
1162
1821
|
uri AS source_uri,
|
|
1163
|
-
->link
|
|
1822
|
+
->link AS links
|
|
1164
1823
|
FROM node
|
|
1165
1824
|
WHERE ${whereConditions.join(' AND ')}
|
|
1825
|
+
FETCH links
|
|
1166
1826
|
`.trim();
|
|
1167
1827
|
|
|
1168
1828
|
return fullQuery;
|
|
@@ -1194,18 +1854,18 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1194
1854
|
const conditions: string[] = [];
|
|
1195
1855
|
|
|
1196
1856
|
for (const [propertyName, condition] of Object.entries(where)) {
|
|
1197
|
-
// Check if this is a special field (
|
|
1857
|
+
// Check if this is a special field (id, author, timestamp)
|
|
1198
1858
|
// Note: author and timestamp filtering is done in JavaScript after query
|
|
1199
|
-
const isSpecial = ['
|
|
1859
|
+
const isSpecial = ['id', 'author', 'timestamp'].includes(propertyName);
|
|
1200
1860
|
|
|
1201
1861
|
if (isSpecial) {
|
|
1202
1862
|
// Skip author and timestamp - they'll be filtered in JavaScript
|
|
1203
|
-
// Only handle '
|
|
1863
|
+
// Only handle 'id' (which maps to 'uri') here
|
|
1204
1864
|
if (propertyName === 'author' || propertyName === 'timestamp') {
|
|
1205
1865
|
continue; // Skip - will be filtered post-query
|
|
1206
1866
|
}
|
|
1207
1867
|
|
|
1208
|
-
const columnName = 'uri'; //
|
|
1868
|
+
const columnName = 'uri'; // id maps to uri in node table
|
|
1209
1869
|
|
|
1210
1870
|
// Handle base/uri field directly
|
|
1211
1871
|
if (Array.isArray(condition)) {
|
|
@@ -1246,7 +1906,54 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1246
1906
|
conditions.push(`${columnName} = ${this.formatSurrealValue(condition)}`);
|
|
1247
1907
|
}
|
|
1248
1908
|
} else {
|
|
1249
|
-
// Handle regular properties via graph traversal
|
|
1909
|
+
// Handle regular properties via graph traversal.
|
|
1910
|
+
// IMPORTANT: Check relation metadata first — @BelongsToOne / @BelongsToMany
|
|
1911
|
+
// also write into propertyRegistry, but the link direction is inverted.
|
|
1912
|
+
// If we matched the property path they would get a forward ->link filter
|
|
1913
|
+
// which is wrong for belongs-to relations.
|
|
1914
|
+
const allRelations = getRelationsMetadata(this);
|
|
1915
|
+
const relMeta = allRelations[propertyName];
|
|
1916
|
+
const isBelongs = relMeta?.kind === 'belongsToOne' || relMeta?.kind === 'belongsToMany';
|
|
1917
|
+
|
|
1918
|
+
if (relMeta) {
|
|
1919
|
+
const predicate = escapeSurrealString(relMeta.predicate);
|
|
1920
|
+
|
|
1921
|
+
if (Array.isArray(condition)) {
|
|
1922
|
+
const formattedValues = condition.map(v => this.formatSurrealValue(v)).join(', ');
|
|
1923
|
+
if (isBelongs) {
|
|
1924
|
+
conditions.push(`count(<-link[WHERE predicate = '${predicate}' AND in.uri IN [${formattedValues}]]) > 0`);
|
|
1925
|
+
} else {
|
|
1926
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}' AND out.uri IN [${formattedValues}]]) > 0`);
|
|
1927
|
+
}
|
|
1928
|
+
} else if (typeof condition === 'object' && condition !== null) {
|
|
1929
|
+
const ops = condition as any;
|
|
1930
|
+
if (ops.not !== undefined) {
|
|
1931
|
+
if (Array.isArray(ops.not)) {
|
|
1932
|
+
const formattedValues = ops.not.map(v => this.formatSurrealValue(v)).join(', ');
|
|
1933
|
+
if (isBelongs) {
|
|
1934
|
+
conditions.push(`count(<-link[WHERE predicate = '${predicate}' AND in.uri IN [${formattedValues}]]) = 0`);
|
|
1935
|
+
} else {
|
|
1936
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}' AND out.uri IN [${formattedValues}]]) = 0`);
|
|
1937
|
+
}
|
|
1938
|
+
} else {
|
|
1939
|
+
if (isBelongs) {
|
|
1940
|
+
conditions.push(`count(<-link[WHERE predicate = '${predicate}' AND in.uri = ${this.formatSurrealValue(ops.not)}]) = 0`);
|
|
1941
|
+
} else {
|
|
1942
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}' AND out.uri = ${this.formatSurrealValue(ops.not)}]) = 0`);
|
|
1943
|
+
}
|
|
1944
|
+
}
|
|
1945
|
+
}
|
|
1946
|
+
} else {
|
|
1947
|
+
// Simple equality
|
|
1948
|
+
if (isBelongs) {
|
|
1949
|
+
conditions.push(`count(<-link[WHERE predicate = '${predicate}' AND in.uri = ${this.formatSurrealValue(condition)}]) > 0`);
|
|
1950
|
+
} else {
|
|
1951
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}' AND out.uri = ${this.formatSurrealValue(condition)}]) > 0`);
|
|
1952
|
+
}
|
|
1953
|
+
}
|
|
1954
|
+
continue;
|
|
1955
|
+
}
|
|
1956
|
+
|
|
1250
1957
|
const propMeta = metadata.properties[propertyName];
|
|
1251
1958
|
if (!propMeta) continue; // Skip if property not found in metadata
|
|
1252
1959
|
|
|
@@ -1257,7 +1964,7 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1257
1964
|
if (Array.isArray(condition)) {
|
|
1258
1965
|
// Array values (IN clause)
|
|
1259
1966
|
const formattedValues = condition.map(v => this.formatSurrealValue(v)).join(', ');
|
|
1260
|
-
conditions.push(`count(->link[WHERE
|
|
1967
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}' AND ${targetField} IN [${formattedValues}]]) > 0`);
|
|
1261
1968
|
} else if (typeof condition === 'object' && condition !== null) {
|
|
1262
1969
|
// Operator object
|
|
1263
1970
|
const ops = condition as any;
|
|
@@ -1265,10 +1972,10 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1265
1972
|
if (Array.isArray(ops.not)) {
|
|
1266
1973
|
// For NOT IN with array: must NOT have a link with value in the array
|
|
1267
1974
|
const formattedValues = ops.not.map(v => this.formatSurrealValue(v)).join(', ');
|
|
1268
|
-
conditions.push(`count(->link[WHERE
|
|
1975
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}' AND ${targetField} IN [${formattedValues}]]) = 0`);
|
|
1269
1976
|
} else {
|
|
1270
1977
|
// For NOT with single value: must NOT have this value
|
|
1271
|
-
conditions.push(`count(->link[WHERE
|
|
1978
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(ops.not)}]) = 0`);
|
|
1272
1979
|
}
|
|
1273
1980
|
}
|
|
1274
1981
|
// Note: gt, gte, lt, lte, between, contains operators are filtered in JavaScript
|
|
@@ -1281,11 +1988,11 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1281
1988
|
ops.between !== undefined || ops.contains !== undefined;
|
|
1282
1989
|
if (hasComparisonOps) {
|
|
1283
1990
|
// Ensure we only get nodes that have this property
|
|
1284
|
-
conditions.push(`count(->link[WHERE
|
|
1991
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}']) > 0`);
|
|
1285
1992
|
}
|
|
1286
1993
|
} else {
|
|
1287
1994
|
// Simple equality
|
|
1288
|
-
conditions.push(`count(->link[WHERE
|
|
1995
|
+
conditions.push(`count(->link[WHERE predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(condition)}]) > 0`);
|
|
1289
1996
|
}
|
|
1290
1997
|
}
|
|
1291
1998
|
}
|
|
@@ -1325,19 +2032,19 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1325
2032
|
const conditions: string[] = [];
|
|
1326
2033
|
|
|
1327
2034
|
for (const [propertyName, condition] of Object.entries(where)) {
|
|
1328
|
-
// Check if this is a special field (
|
|
2035
|
+
// Check if this is a special field (id, author, timestamp)
|
|
1329
2036
|
// Note: author and timestamp filtering is done in JavaScript after GROUP BY
|
|
1330
2037
|
// because they need to be computed from the grouped links first
|
|
1331
|
-
const isSpecial = ['
|
|
2038
|
+
const isSpecial = ['id', 'author', 'timestamp'].includes(propertyName);
|
|
1332
2039
|
|
|
1333
2040
|
if (isSpecial) {
|
|
1334
2041
|
// Skip author and timestamp - they'll be filtered in JavaScript
|
|
1335
|
-
// Only handle '
|
|
2042
|
+
// Only handle 'id' (which maps to 'source') here
|
|
1336
2043
|
if (propertyName === 'author' || propertyName === 'timestamp') {
|
|
1337
2044
|
continue; // Skip - will be filtered post-query
|
|
1338
2045
|
}
|
|
1339
2046
|
|
|
1340
|
-
const columnName = 'source'; //
|
|
2047
|
+
const columnName = 'source'; // id maps to source
|
|
1341
2048
|
|
|
1342
2049
|
// Handle base/source field directly
|
|
1343
2050
|
if (Array.isArray(condition)) {
|
|
@@ -1429,26 +2136,26 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1429
2136
|
* Builds the SELECT fields for SurrealQL queries.
|
|
1430
2137
|
*
|
|
1431
2138
|
* @description
|
|
1432
|
-
* Generates the field list for the SELECT clause, resolving properties and
|
|
2139
|
+
* Generates the field list for the SELECT clause, resolving properties and relations
|
|
1433
2140
|
* via subqueries. Each property is fetched with a subquery that finds the link with the
|
|
1434
|
-
* appropriate predicate and returns its target.
|
|
2141
|
+
* appropriate predicate and returns its target. Relations are similar but don't use LIMIT 1.
|
|
1435
2142
|
*
|
|
1436
2143
|
* Field types:
|
|
1437
2144
|
* - Properties: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X' LIMIT 1) AS propName`
|
|
1438
|
-
* -
|
|
2145
|
+
* - Relations: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X') AS relName`
|
|
1439
2146
|
* - Author/Timestamp: Always included to provide metadata about each instance
|
|
1440
2147
|
*
|
|
1441
|
-
* If properties or
|
|
1442
|
-
* Otherwise, all properties/
|
|
2148
|
+
* If properties or relations arrays are provided, only those fields are included.
|
|
2149
|
+
* Otherwise, all properties/relations from metadata are included.
|
|
1443
2150
|
*
|
|
1444
|
-
* @param metadata - Model metadata containing property and
|
|
2151
|
+
* @param metadata - Model metadata containing property and relation predicates
|
|
1445
2152
|
* @param properties - Optional array of property names to include (default: all)
|
|
1446
|
-
* @param
|
|
2153
|
+
* @param relations - Optional array of relation names to include (default: all)
|
|
1447
2154
|
* @returns Comma-separated SELECT field list
|
|
1448
2155
|
*
|
|
1449
2156
|
* @private
|
|
1450
2157
|
*/
|
|
1451
|
-
private static buildSurrealSelectFields(metadata: ModelMetadata, properties?: string[],
|
|
2158
|
+
private static buildSurrealSelectFields(metadata: ModelMetadata, properties?: string[], relations?: string[]): string {
|
|
1452
2159
|
const fields: string[] = [];
|
|
1453
2160
|
|
|
1454
2161
|
// Determine properties to fetch
|
|
@@ -1462,15 +2169,15 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1462
2169
|
fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${escapedPredicate}' LIMIT 1) AS ${propName}`);
|
|
1463
2170
|
}
|
|
1464
2171
|
|
|
1465
|
-
// Determine
|
|
1466
|
-
const
|
|
1467
|
-
for (const
|
|
1468
|
-
const
|
|
1469
|
-
if (!
|
|
2172
|
+
// Determine relations to fetch
|
|
2173
|
+
const relsToFetch = relations || Object.keys(metadata.relations);
|
|
2174
|
+
for (const relName of relsToFetch) {
|
|
2175
|
+
const relMeta = metadata.relations[relName];
|
|
2176
|
+
if (!relMeta) continue; // Skip if not found
|
|
1470
2177
|
|
|
1471
2178
|
// Reference source directly since we're selecting from link table
|
|
1472
|
-
const escapedPredicate = escapeSurrealString(
|
|
1473
|
-
fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${escapedPredicate}') AS ${
|
|
2179
|
+
const escapedPredicate = escapeSurrealString(relMeta.predicate);
|
|
2180
|
+
fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${escapedPredicate}') AS ${relName}`);
|
|
1474
2181
|
}
|
|
1475
2182
|
|
|
1476
2183
|
// Always add author and timestamp fields
|
|
@@ -1487,7 +2194,7 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1487
2194
|
*
|
|
1488
2195
|
* @private
|
|
1489
2196
|
*/
|
|
1490
|
-
private static buildSurrealSelectFieldsWithAggregation(metadata: ModelMetadata, properties?: string[],
|
|
2197
|
+
private static buildSurrealSelectFieldsWithAggregation(metadata: ModelMetadata, properties?: string[], relations?: string[]): string {
|
|
1491
2198
|
const fields: string[] = [];
|
|
1492
2199
|
|
|
1493
2200
|
// Determine properties to fetch
|
|
@@ -1501,15 +2208,15 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1501
2208
|
fields.push(`array::first(target[WHERE predicate = '${escapedPredicate}']) AS ${propName}`);
|
|
1502
2209
|
}
|
|
1503
2210
|
|
|
1504
|
-
// Determine
|
|
1505
|
-
const
|
|
1506
|
-
for (const
|
|
1507
|
-
const
|
|
1508
|
-
if (!
|
|
2211
|
+
// Determine relations to fetch
|
|
2212
|
+
const relsToFetch = relations || Object.keys(metadata.relations);
|
|
2213
|
+
for (const relName of relsToFetch) {
|
|
2214
|
+
const relMeta = metadata.relations[relName];
|
|
2215
|
+
if (!relMeta) continue; // Skip if not found
|
|
1509
2216
|
|
|
1510
2217
|
// Use array filtering to get all target values for this predicate
|
|
1511
|
-
const escapedPredicate = escapeSurrealString(
|
|
1512
|
-
fields.push(`target[WHERE predicate = '${escapedPredicate}'] AS ${
|
|
2218
|
+
const escapedPredicate = escapeSurrealString(relMeta.predicate);
|
|
2219
|
+
fields.push(`target[WHERE predicate = '${escapedPredicate}'] AS ${relName}`);
|
|
1513
2220
|
}
|
|
1514
2221
|
|
|
1515
2222
|
// Always add author and timestamp fields
|
|
@@ -1563,15 +2270,15 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1563
2270
|
): Promise<ResultsWithTotalCount<T>> {
|
|
1564
2271
|
if (!result?.[0]?.AllInstances) return { results: [], totalCount: 0 };
|
|
1565
2272
|
// Map results to instances
|
|
1566
|
-
const
|
|
2273
|
+
const requestedProperties = query?.properties || [];
|
|
1567
2274
|
const allInstances = await Promise.all(
|
|
1568
2275
|
result[0].AllInstances.map(async ([Base, Properties, Collections, Timestamp, Author]) => {
|
|
1569
2276
|
try {
|
|
1570
2277
|
const instance = new this(perspective, Base) as any;
|
|
1571
2278
|
// Remove unrequested attributes from instance
|
|
1572
|
-
if (
|
|
2279
|
+
if (requestedProperties.length) {
|
|
1573
2280
|
Object.keys(instance).forEach((key) => {
|
|
1574
|
-
if (!
|
|
2281
|
+
if (!requestedProperties.includes(key) && key !== 'createdAt' && key !== 'updatedAt' && key !== 'author' && key !== 'id' && key !== 'baseExpression') delete instance[key];
|
|
1575
2282
|
});
|
|
1576
2283
|
}
|
|
1577
2284
|
// Collect values to assign to instance
|
|
@@ -1586,7 +2293,24 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1586
2293
|
}
|
|
1587
2294
|
})
|
|
1588
2295
|
);
|
|
1589
|
-
|
|
2296
|
+
const instances = allInstances.filter((instance) => instance !== null) as T[];
|
|
2297
|
+
|
|
2298
|
+
// Eager-load relations if requested (BEFORE snapshot so dirty tracking is accurate)
|
|
2299
|
+
if (query.include && instances.length > 0) {
|
|
2300
|
+
await this.hydrateRelations(instances, perspective, query.include);
|
|
2301
|
+
}
|
|
2302
|
+
|
|
2303
|
+
// Take snapshots for dirty tracking after ALL hydration is complete
|
|
2304
|
+
// (including eager-loaded relations).
|
|
2305
|
+
// When `include` is specified, only snapshot those relations.
|
|
2306
|
+
// Otherwise snapshot ALL fields (properties + relations) since
|
|
2307
|
+
// hydrateFromLinks populates relations with stable raw IDs.
|
|
2308
|
+
const snapshotRelations = query.include;
|
|
2309
|
+
for (const inst of instances) {
|
|
2310
|
+
(inst as Ad4mModel).takeSnapshot(snapshotRelations);
|
|
2311
|
+
}
|
|
2312
|
+
|
|
2313
|
+
return { results: instances, totalCount: result[0].TotalCount };
|
|
1590
2314
|
}
|
|
1591
2315
|
|
|
1592
2316
|
/**
|
|
@@ -1609,7 +2333,6 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1609
2333
|
|
|
1610
2334
|
const metadata = this.getModelMetadata();
|
|
1611
2335
|
const requestedProperties = query?.properties || [];
|
|
1612
|
-
const requestedCollections = query?.collections || [];
|
|
1613
2336
|
|
|
1614
2337
|
// The query used GROUP BY with graph traversal, so each row has:
|
|
1615
2338
|
// - source: the node ID (e.g., "node:abc123")
|
|
@@ -1631,254 +2354,73 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1631
2354
|
const links = row.links || [];
|
|
1632
2355
|
|
|
1633
2356
|
const instance = new this(perspective, base) as any;
|
|
2357
|
+
|
|
2358
|
+
// Core hydration via unified helper (pass requestedProperties for sparse fieldset)
|
|
2359
|
+
await this.hydrateFromLinks(instance, links, metadata, perspective, requestedProperties.length > 0 ? requestedProperties : undefined);
|
|
1634
2360
|
|
|
1635
|
-
//
|
|
1636
|
-
|
|
1637
|
-
|
|
1638
|
-
|
|
1639
|
-
|
|
1640
|
-
|
|
1641
|
-
|
|
1642
|
-
for (let linkIndex = 0; linkIndex < links.length; linkIndex++) {
|
|
1643
|
-
const link = links[linkIndex];
|
|
1644
|
-
const predicate = link.predicate;
|
|
1645
|
-
const target = link.target;
|
|
1646
|
-
|
|
1647
|
-
// Skip 'None' values
|
|
1648
|
-
if (target === 'None') continue;
|
|
1649
|
-
|
|
1650
|
-
// Track both earliest (createdAt) and latest (updatedAt) timestamps with their authors
|
|
1651
|
-
if (link.timestamp) {
|
|
1652
|
-
if (!minTimestamp || link.timestamp < minTimestamp) {
|
|
1653
|
-
minTimestamp = link.timestamp;
|
|
1654
|
-
originalAuthor = link.author;
|
|
1655
|
-
}
|
|
1656
|
-
if (!maxTimestamp || link.timestamp > maxTimestamp) {
|
|
1657
|
-
maxTimestamp = link.timestamp;
|
|
1658
|
-
latestAuthor = link.author;
|
|
2361
|
+
// When specific properties are requested, delete unrequested properties
|
|
2362
|
+
// so they return undefined instead of their constructor defaults (e.g. 0, [])
|
|
2363
|
+
if (requestedProperties.length > 0) {
|
|
2364
|
+
const requested = new Set(requestedProperties);
|
|
2365
|
+
for (const propName of Object.keys(metadata.properties)) {
|
|
2366
|
+
if (!requested.has(propName)) {
|
|
2367
|
+
delete instance[propName];
|
|
1659
2368
|
}
|
|
1660
2369
|
}
|
|
1661
|
-
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
|
-
for (const [propName, propMeta] of Object.entries(metadata.properties)) {
|
|
1665
|
-
if (propMeta.getter) continue; // Handle via getter evaluation
|
|
1666
|
-
if (propMeta.predicate === predicate) {
|
|
1667
|
-
// For properties, take the first value (or we could use timestamp to get latest)
|
|
1668
|
-
// Note: Empty objects {} are truthy, so we need to check for them explicitly
|
|
1669
|
-
const currentValue = instance[propName];
|
|
1670
|
-
const isEmptyObject = typeof currentValue === 'object' && currentValue !== null && !Array.isArray(currentValue) && Object.keys(currentValue).length === 0;
|
|
1671
|
-
if (!currentValue || currentValue === "" || currentValue === 0 || isEmptyObject) {
|
|
1672
|
-
let convertedValue = target;
|
|
1673
|
-
|
|
1674
|
-
// Only process if target has a value
|
|
1675
|
-
if (target !== undefined && target !== null && target !== '') {
|
|
1676
|
-
// Check if we need to resolve a non-literal language expression.
|
|
1677
|
-
// resolveLanguage must be defined and not 'literal' to trigger expression resolution.
|
|
1678
|
-
// Also skip if the target itself is a literal:// URI — those are handled by the
|
|
1679
|
-
// literal-parsing branch below (avoids calling getExpression on empty literals like
|
|
1680
|
-
// "literal://string:" which would cause a deserialization error).
|
|
1681
|
-
if (propMeta.resolveLanguage != undefined && propMeta.resolveLanguage !== 'literal' && typeof target === 'string' && !target.startsWith('literal://')) {
|
|
1682
|
-
// For non-literal languages, resolve the expression via perspective.getExpression()
|
|
1683
|
-
// Note: Literals are already parsed by SurrealDB's fn::parse_literal()
|
|
1684
|
-
try {
|
|
1685
|
-
const expression = await perspective.getExpression(target);
|
|
1686
|
-
if (expression) {
|
|
1687
|
-
// Parse the expression data if it's a JSON string
|
|
1688
|
-
try {
|
|
1689
|
-
convertedValue = JSON.parse(expression.data);
|
|
1690
|
-
} catch {
|
|
1691
|
-
// If parsing fails, use the data as-is
|
|
1692
|
-
convertedValue = expression.data;
|
|
1693
|
-
}
|
|
1694
|
-
}
|
|
1695
|
-
} catch (e) {
|
|
1696
|
-
console.warn(`Failed to resolve expression for ${propName} with target "${target}":`, e);
|
|
1697
|
-
console.warn("Falling back to raw value");
|
|
1698
|
-
convertedValue = target; // Fall back to raw value
|
|
1699
|
-
}
|
|
1700
|
-
} else if (propMeta.resolveLanguage === 'literal' && typeof target === 'string' && target.startsWith('literal://')) {
|
|
1701
|
-
// Only parse literal URIs when resolveLanguage is explicitly set to 'literal'.
|
|
1702
|
-
// Without this check, properties pointing to baseExpressions of other models
|
|
1703
|
-
// (which may be literal:// strings) would get unwrapped, breaking link URI validation.
|
|
1704
|
-
try {
|
|
1705
|
-
const parsed = Literal.fromUrl(target).get();
|
|
1706
|
-
if(parsed.data !== undefined) {
|
|
1707
|
-
convertedValue = parsed.data;
|
|
1708
|
-
} else {
|
|
1709
|
-
convertedValue = parsed;
|
|
1710
|
-
}
|
|
1711
|
-
} catch (e) {
|
|
1712
|
-
// If literal parsing fails, just use the value as-is (don't bail)
|
|
1713
|
-
convertedValue = target;
|
|
1714
|
-
}
|
|
1715
|
-
} else if (typeof target === 'string') {
|
|
1716
|
-
// Type conversion: check the instance property's current type
|
|
1717
|
-
const expectedType = typeof instance[propName];
|
|
1718
|
-
if (expectedType === 'number') {
|
|
1719
|
-
convertedValue = Number(target);
|
|
1720
|
-
} else if (expectedType === 'boolean') {
|
|
1721
|
-
convertedValue = target === 'true' || target === '1';
|
|
1722
|
-
}
|
|
1723
|
-
}
|
|
1724
|
-
}
|
|
1725
|
-
|
|
1726
|
-
// Apply transform function if it exists
|
|
1727
|
-
if (propMeta.transform && typeof propMeta.transform === 'function') {
|
|
1728
|
-
convertedValue = propMeta.transform(convertedValue);
|
|
1729
|
-
}
|
|
1730
|
-
|
|
1731
|
-
instance[propName] = convertedValue;
|
|
1732
|
-
}
|
|
1733
|
-
foundProperty = true;
|
|
1734
|
-
break;
|
|
2370
|
+
for (const relName of Object.keys(metadata.relations)) {
|
|
2371
|
+
if (!requested.has(relName) && !(query.include && relName in query.include)) {
|
|
2372
|
+
delete instance[relName];
|
|
1735
2373
|
}
|
|
1736
2374
|
}
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
1741
|
-
if (collMeta.getter) continue; // Handle via getter evaluation
|
|
1742
|
-
if (collMeta.predicate === predicate) {
|
|
1743
|
-
// For collections, accumulate all values with their timestamps and indices for sorting
|
|
1744
|
-
if (!instance[collName]) {
|
|
1745
|
-
instance[collName] = [];
|
|
1746
|
-
}
|
|
1747
|
-
// Initialize timestamp tracking array if not already done
|
|
1748
|
-
const timestampsKey = `__${collName}_timestamps`;
|
|
1749
|
-
const indicesKey = `__${collName}_indices`;
|
|
1750
|
-
if (!instance[timestampsKey]) {
|
|
1751
|
-
instance[timestampsKey] = [];
|
|
1752
|
-
}
|
|
1753
|
-
if (!instance[indicesKey]) {
|
|
1754
|
-
instance[indicesKey] = [];
|
|
1755
|
-
}
|
|
1756
|
-
if (!instance[collName].includes(target)) {
|
|
1757
|
-
instance[collName].push(target);
|
|
1758
|
-
instance[timestampsKey].push(link.timestamp || '');
|
|
1759
|
-
// Track original position in the links array for stable sorting
|
|
1760
|
-
instance[indicesKey].push(linkIndex);
|
|
1761
|
-
}
|
|
1762
|
-
break;
|
|
1763
|
-
}
|
|
2375
|
+
// Also strip metadata fields unless explicitly requested
|
|
2376
|
+
for (const metaField of ['author', 'createdAt', 'updatedAt'] as const) {
|
|
2377
|
+
if (!requested.has(metaField)) {
|
|
2378
|
+
delete instance[metaField];
|
|
1764
2379
|
}
|
|
1765
2380
|
}
|
|
1766
2381
|
}
|
|
1767
|
-
|
|
1768
|
-
// Set author and timestamps
|
|
1769
|
-
if (originalAuthor) {
|
|
1770
|
-
instance.author = originalAuthor;
|
|
1771
|
-
}
|
|
1772
|
-
|
|
1773
|
-
// Set createdAt from earliest timestamp
|
|
1774
|
-
if (minTimestamp) {
|
|
1775
|
-
if (typeof minTimestamp === 'string' && minTimestamp.includes('T')) {
|
|
1776
|
-
instance.createdAt = new Date(minTimestamp).getTime();
|
|
1777
|
-
} else if (typeof minTimestamp === 'string') {
|
|
1778
|
-
const parsed = parseInt(minTimestamp, 10);
|
|
1779
|
-
instance.createdAt = isNaN(parsed) ? minTimestamp : parsed;
|
|
1780
|
-
} else {
|
|
1781
|
-
instance.createdAt = minTimestamp;
|
|
1782
|
-
}
|
|
1783
|
-
}
|
|
1784
|
-
|
|
1785
|
-
// Set updatedAt from most recent timestamp
|
|
1786
|
-
if (maxTimestamp) {
|
|
1787
|
-
if (typeof maxTimestamp === 'string' && maxTimestamp.includes('T')) {
|
|
1788
|
-
instance.updatedAt = new Date(maxTimestamp).getTime();
|
|
1789
|
-
} else if (typeof maxTimestamp === 'string') {
|
|
1790
|
-
const parsed = parseInt(maxTimestamp, 10);
|
|
1791
|
-
instance.updatedAt = isNaN(parsed) ? maxTimestamp : parsed;
|
|
1792
|
-
} else {
|
|
1793
|
-
instance.updatedAt = maxTimestamp;
|
|
1794
|
-
}
|
|
1795
|
-
}
|
|
1796
|
-
|
|
1797
|
-
// Sort collections by timestamp to maintain insertion order
|
|
1798
|
-
for (const [collName, collMeta] of Object.entries(metadata.collections)) {
|
|
1799
|
-
const timestampsKey = `__${collName}_timestamps`;
|
|
1800
|
-
const indicesKey = `__${collName}_indices`;
|
|
1801
|
-
if (instance[collName] && instance[timestampsKey]) {
|
|
1802
|
-
// Create array of [value, timestamp, index] tuples
|
|
1803
|
-
const pairs = instance[collName].map((value: any, index: number) => ({
|
|
1804
|
-
value,
|
|
1805
|
-
timestamp: instance[timestampsKey][index] || '',
|
|
1806
|
-
originalIndex: instance[indicesKey]?.[index] ?? index
|
|
1807
|
-
}));
|
|
1808
|
-
// Sort by timestamp first, then by original index for stable sorting
|
|
1809
|
-
pairs.sort((a, b) => {
|
|
1810
|
-
const tsA = String(a.timestamp || '');
|
|
1811
|
-
const tsB = String(b.timestamp || '');
|
|
1812
|
-
const tsCompare = tsA.localeCompare(tsB);
|
|
1813
|
-
if (tsCompare !== 0) return tsCompare;
|
|
1814
|
-
// Use original index as tiebreaker for stable sorting
|
|
1815
|
-
return a.originalIndex - b.originalIndex;
|
|
1816
|
-
});
|
|
1817
|
-
// Replace collection with sorted values, filtering out empty strings and None
|
|
1818
|
-
instance[collName] = pairs
|
|
1819
|
-
.map(p => p.value)
|
|
1820
|
-
.filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None');
|
|
1821
|
-
// Clean up temporary arrays
|
|
1822
|
-
delete instance[timestampsKey];
|
|
1823
|
-
delete instance[indicesKey];
|
|
1824
|
-
}
|
|
1825
|
-
}
|
|
1826
|
-
|
|
1827
|
-
// Filter by requested attributes if specified
|
|
1828
|
-
if (requestedProperties.length > 0 || requestedCollections.length > 0) {
|
|
1829
|
-
const requestedAttributes = [...requestedProperties, ...requestedCollections];
|
|
1830
|
-
Object.keys(instance).forEach((key) => {
|
|
1831
|
-
// Keep only requested attributes, plus always keep createdAt, updatedAt, author, and baseExpression
|
|
1832
|
-
// Note: timestamp is a getter alias for createdAt, so we preserve createdAt instead
|
|
1833
|
-
if (!requestedAttributes.includes(key) && key !== 'createdAt' && key !== 'updatedAt' && key !== 'author' && key !== 'baseExpression') {
|
|
1834
|
-
delete instance[key];
|
|
1835
|
-
}
|
|
1836
|
-
});
|
|
1837
|
-
}
|
|
1838
|
-
|
|
2382
|
+
|
|
1839
2383
|
instances.push(instance);
|
|
1840
2384
|
} catch (error) {
|
|
1841
2385
|
console.error(`Failed to process SurrealDB instance ${base}:`, error);
|
|
1842
2386
|
}
|
|
1843
2387
|
}
|
|
1844
|
-
|
|
2388
|
+
|
|
2389
|
+
// Populate reverse relation fields (belongsToOne / belongsToMany) as string IDs.
|
|
2390
|
+
// These relations point FROM other nodes TO this instance, so they cannot be resolved
|
|
2391
|
+
// from the node's own outgoing links fetched above. We do a reverse-link lookup here
|
|
2392
|
+
// so that these fields are populated as IDs even without an explicit include.
|
|
2393
|
+
const allRelsMeta = getRelationsMetadata(this as any);
|
|
2394
|
+
const reverseRelEntries = Object.entries(allRelsMeta).filter(
|
|
2395
|
+
([relName, meta]) =>
|
|
2396
|
+
(meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') &&
|
|
2397
|
+
(requestedProperties.length === 0 || requestedProperties.includes(relName))
|
|
2398
|
+
);
|
|
2399
|
+
if (reverseRelEntries.length > 0 && instances.length > 0) {
|
|
2400
|
+
await Promise.all(
|
|
2401
|
+
instances.map(async (inst) => {
|
|
2402
|
+
for (const [relName, relMeta] of reverseRelEntries) {
|
|
2403
|
+
const reverseLinks = await perspective.get(
|
|
2404
|
+
new LinkQuery({ predicate: relMeta.predicate, target: inst.id })
|
|
2405
|
+
);
|
|
2406
|
+
const sourceIds = reverseLinks
|
|
2407
|
+
.filter((l) => l.data.target === inst.id)
|
|
2408
|
+
.map((l) => l.data.source);
|
|
2409
|
+
if (relMeta.kind === 'belongsToOne') {
|
|
2410
|
+
(inst as any)[relName] = sourceIds.length > 0 ? sourceIds[sourceIds.length - 1] : null;
|
|
2411
|
+
} else {
|
|
2412
|
+
(inst as any)[relName] = sourceIds;
|
|
2413
|
+
}
|
|
2414
|
+
}
|
|
2415
|
+
})
|
|
2416
|
+
);
|
|
2417
|
+
}
|
|
2418
|
+
|
|
1845
2419
|
// Evaluate custom getters for all instances (single pass)
|
|
1846
|
-
// This populates collection values needed for where.isInstance filtering
|
|
1847
2420
|
for (const instance of instances) {
|
|
1848
2421
|
await this.evaluateCustomGettersForInstance(instance, perspective, metadata);
|
|
1849
2422
|
}
|
|
1850
2423
|
|
|
1851
|
-
// Filter collections by where.isInstance if specified
|
|
1852
|
-
// Do this after initial evaluation so collection values exist for filtering
|
|
1853
|
-
for (const instance of instances) {
|
|
1854
|
-
for (const [collName, collMeta] of Object.entries(metadata.collections)) {
|
|
1855
|
-
if (collMeta.where?.isInstance && instance[collName]?.length > 0) {
|
|
1856
|
-
try {
|
|
1857
|
-
const targetClass = collMeta.where.isInstance;
|
|
1858
|
-
const subjects = instance[collName];
|
|
1859
|
-
|
|
1860
|
-
// Get the class metadata from SDNA to pass to batchCheckSubjectInstances
|
|
1861
|
-
const targetClassName = typeof targetClass === 'string'
|
|
1862
|
-
? targetClass
|
|
1863
|
-
: (targetClass as any).prototype?.className || targetClass.name;
|
|
1864
|
-
const classMetadata = await perspective.getSubjectClassMetadataFromSDNA(targetClassName);
|
|
1865
|
-
|
|
1866
|
-
if (!classMetadata) {
|
|
1867
|
-
continue;
|
|
1868
|
-
}
|
|
1869
|
-
|
|
1870
|
-
// Check which subjects are instances of the target class
|
|
1871
|
-
const validSubjects = await perspective.batchCheckSubjectInstances(subjects, classMetadata);
|
|
1872
|
-
|
|
1873
|
-
// Update the collection with filtered instances
|
|
1874
|
-
instance[collName] = validSubjects;
|
|
1875
|
-
} catch (error) {
|
|
1876
|
-
// On error, leave the collection unfiltered rather than breaking everything
|
|
1877
|
-
}
|
|
1878
|
-
}
|
|
1879
|
-
}
|
|
1880
|
-
}
|
|
1881
|
-
|
|
1882
2424
|
// Filter by where conditions that couldn't be filtered in SQL
|
|
1883
2425
|
// This includes:
|
|
1884
2426
|
// - author/timestamp (computed from grouped links)
|
|
@@ -1925,30 +2467,34 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1925
2467
|
(query.limit !== undefined || query.offset !== undefined ? { timestamp: 'ASC' as 'ASC' } : null);
|
|
1926
2468
|
|
|
1927
2469
|
if (effectiveOrder) {
|
|
1928
|
-
const
|
|
1929
|
-
const orderDirection = Object.values(effectiveOrder)[0];
|
|
2470
|
+
const orderEntries = Object.entries(effectiveOrder);
|
|
1930
2471
|
|
|
1931
2472
|
filteredInstances.sort((a: any, b: any) => {
|
|
1932
|
-
|
|
1933
|
-
|
|
1934
|
-
|
|
1935
|
-
|
|
1936
|
-
|
|
1937
|
-
|
|
1938
|
-
|
|
1939
|
-
|
|
1940
|
-
|
|
1941
|
-
|
|
1942
|
-
|
|
1943
|
-
|
|
1944
|
-
|
|
1945
|
-
|
|
1946
|
-
|
|
1947
|
-
|
|
1948
|
-
|
|
1949
|
-
|
|
2473
|
+
for (const [orderPropName, orderDirection] of orderEntries) {
|
|
2474
|
+
let aVal = a[orderPropName];
|
|
2475
|
+
let bVal = b[orderPropName];
|
|
2476
|
+
|
|
2477
|
+
// Handle undefined values - push them to the end
|
|
2478
|
+
if (aVal === undefined && bVal === undefined) continue;
|
|
2479
|
+
if (aVal === undefined) return orderDirection === 'ASC' ? 1 : -1;
|
|
2480
|
+
if (bVal === undefined) return orderDirection === 'ASC' ? -1 : 1;
|
|
2481
|
+
|
|
2482
|
+
// Compare values
|
|
2483
|
+
let comparison = 0;
|
|
2484
|
+
if (typeof aVal === 'number' && typeof bVal === 'number') {
|
|
2485
|
+
comparison = aVal - bVal;
|
|
2486
|
+
} else if (typeof aVal === 'string' && typeof bVal === 'string') {
|
|
2487
|
+
comparison = aVal.localeCompare(bVal);
|
|
2488
|
+
} else {
|
|
2489
|
+
comparison = String(aVal).localeCompare(String(bVal));
|
|
2490
|
+
}
|
|
1950
2491
|
|
|
1951
|
-
|
|
2492
|
+
if (comparison !== 0) {
|
|
2493
|
+
return orderDirection === 'DESC' ? -comparison : comparison;
|
|
2494
|
+
}
|
|
2495
|
+
// comparison === 0: continue to next sort field
|
|
2496
|
+
}
|
|
2497
|
+
return 0;
|
|
1952
2498
|
});
|
|
1953
2499
|
}
|
|
1954
2500
|
|
|
@@ -1963,6 +2509,22 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
1963
2509
|
paginatedInstances = filteredInstances.slice(start, end);
|
|
1964
2510
|
}
|
|
1965
2511
|
|
|
2512
|
+
// Eager-load relations if requested (BEFORE snapshot so dirty tracking is accurate)
|
|
2513
|
+
if (query.include && paginatedInstances.length > 0) {
|
|
2514
|
+
await this.hydrateRelations(paginatedInstances, perspective, query.include);
|
|
2515
|
+
}
|
|
2516
|
+
|
|
2517
|
+
// Take snapshots for dirty tracking after ALL hydration is complete
|
|
2518
|
+
// (including eager-loaded relations).
|
|
2519
|
+
// When `include` is specified, only snapshot those relations.
|
|
2520
|
+
// Otherwise snapshot ALL fields (properties + relations) since
|
|
2521
|
+
// hydrateFromLinks populates relations with stable raw IDs —
|
|
2522
|
+
// this ensures push-to-array + save() correctly detects dirty relations.
|
|
2523
|
+
const snapshotRelations = query.include;
|
|
2524
|
+
for (const inst of paginatedInstances) {
|
|
2525
|
+
(inst as Ad4mModel).takeSnapshot(snapshotRelations);
|
|
2526
|
+
}
|
|
2527
|
+
|
|
1966
2528
|
return {
|
|
1967
2529
|
results: paginatedInstances,
|
|
1968
2530
|
totalCount
|
|
@@ -2067,6 +2629,9 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2067
2629
|
query: Query = {},
|
|
2068
2630
|
useSurrealDB: boolean = true
|
|
2069
2631
|
): Promise<T[]> {
|
|
2632
|
+
if (query.properties && query.properties.length === 0) {
|
|
2633
|
+
throw new Error("properties[] must not be empty — omit the field to return all properties, or specify at least one field name");
|
|
2634
|
+
}
|
|
2070
2635
|
if (useSurrealDB) {
|
|
2071
2636
|
const surrealQuery = await this.queryToSurrealQL(perspective, query);
|
|
2072
2637
|
const result = await perspective.querySurrealDB(surrealQuery);
|
|
@@ -2080,6 +2645,37 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2080
2645
|
}
|
|
2081
2646
|
}
|
|
2082
2647
|
|
|
2648
|
+
/**
|
|
2649
|
+
* Finds the first instance matching the query, or `null` if none exists.
|
|
2650
|
+
*
|
|
2651
|
+
* Equivalent to `findAll` with `limit: 1` — only one instance is hydrated.
|
|
2652
|
+
*
|
|
2653
|
+
* @param perspective - The perspective to search in
|
|
2654
|
+
* @param query - Optional query parameters to filter results
|
|
2655
|
+
* @param useSurrealDB - Whether to use SurrealDB (default: true) or Prolog (legacy)
|
|
2656
|
+
* @returns The first matching instance, or `null`
|
|
2657
|
+
*
|
|
2658
|
+
* @example
|
|
2659
|
+
* ```typescript
|
|
2660
|
+
* const recipe = await Recipe.findOne(perspective, {
|
|
2661
|
+
* where: { name: "Pasta" }
|
|
2662
|
+
* });
|
|
2663
|
+
* if (recipe) {
|
|
2664
|
+
* console.log(recipe.name);
|
|
2665
|
+
* }
|
|
2666
|
+
* ```
|
|
2667
|
+
*/
|
|
2668
|
+
static async findOne<T extends Ad4mModel>(
|
|
2669
|
+
this: typeof Ad4mModel & (new (...args: any[]) => T),
|
|
2670
|
+
perspective: PerspectiveProxy,
|
|
2671
|
+
query: Query = {},
|
|
2672
|
+
useSurrealDB: boolean = true,
|
|
2673
|
+
): Promise<T | null> {
|
|
2674
|
+
const limitedQuery = { ...query, limit: 1 };
|
|
2675
|
+
const results = await this.findAll(perspective, limitedQuery, useSurrealDB);
|
|
2676
|
+
return results[0] ?? null;
|
|
2677
|
+
}
|
|
2678
|
+
|
|
2083
2679
|
/**
|
|
2084
2680
|
* Gets all instances with count of total matches without offset & limit applied.
|
|
2085
2681
|
*
|
|
@@ -2161,9 +2757,12 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2161
2757
|
}
|
|
2162
2758
|
|
|
2163
2759
|
static async countQueryToProlog(perspective: PerspectiveProxy, query: Query = {}, modelClassName?: string | null) {
|
|
2164
|
-
const {
|
|
2760
|
+
const { where } = query;
|
|
2165
2761
|
const className = modelClassName || (await this.getClassName(perspective));
|
|
2166
|
-
const
|
|
2762
|
+
const resolvedParentPredicate = query.parent
|
|
2763
|
+
? resolveParentPredicate(query.parent, this)
|
|
2764
|
+
: undefined;
|
|
2765
|
+
const instanceQueries = [buildAuthorAndTimestampQuery(), buildParentQuery(query.parent, resolvedParentPredicate), buildWhereQuery(where)];
|
|
2167
2766
|
const resultSetQueries = [buildCountQuery(true), buildOrderQuery(), buildOffsetQuery(), buildLimitQuery()];
|
|
2168
2767
|
|
|
2169
2768
|
const fullQuery = `
|
|
@@ -2250,109 +2849,135 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2250
2849
|
}
|
|
2251
2850
|
|
|
2252
2851
|
if (resolveLanguage) {
|
|
2253
|
-
value = await this
|
|
2852
|
+
value = await this._perspective.createExpression(value, resolveLanguage);
|
|
2254
2853
|
}
|
|
2255
2854
|
|
|
2256
|
-
await this
|
|
2855
|
+
await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
|
|
2856
|
+
}
|
|
2857
|
+
|
|
2858
|
+
/** Resolve a relation argument to a plain string ID. Accepts either a raw
|
|
2859
|
+
* string ID or an Ad4mModel instance (in which case `.id` is used). */
|
|
2860
|
+
private resolveRelationId(value: any): string {
|
|
2861
|
+
if (typeof value === 'string') return value;
|
|
2862
|
+
if (value && typeof value === 'object' && typeof value.id === 'string') return value.id;
|
|
2863
|
+
return String(value);
|
|
2257
2864
|
}
|
|
2258
2865
|
|
|
2259
|
-
private async
|
|
2866
|
+
private async setRelationValues(key: string, value: any, batchId?: string) {
|
|
2260
2867
|
// Phase 1: Use metadata instead of Prolog queries
|
|
2261
|
-
const metadata = this.
|
|
2868
|
+
const metadata = this.getRelationOptions(key);
|
|
2262
2869
|
if (!metadata) {
|
|
2263
|
-
console.warn(`
|
|
2870
|
+
console.warn(`Relation "${key}" has no metadata, skipping`);
|
|
2264
2871
|
return;
|
|
2265
2872
|
}
|
|
2266
2873
|
|
|
2267
2874
|
// Generate actions from metadata (replaces Prolog query)
|
|
2268
|
-
const actions = this.
|
|
2875
|
+
const actions = this.generateRelationAction(key, 'setter');
|
|
2269
2876
|
|
|
2270
2877
|
if (value != null) {
|
|
2271
2878
|
if (Array.isArray(value)) {
|
|
2272
|
-
await this
|
|
2879
|
+
await this._perspective.executeAction(
|
|
2273
2880
|
actions,
|
|
2274
|
-
this
|
|
2275
|
-
value.map((v) => ({ name: "value", value: v })),
|
|
2881
|
+
this._baseExpression,
|
|
2882
|
+
value.map((v) => ({ name: "value", value: this.resolveRelationId(v) })),
|
|
2276
2883
|
batchId
|
|
2277
2884
|
);
|
|
2278
2885
|
} else {
|
|
2279
|
-
await this
|
|
2886
|
+
await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
|
|
2280
2887
|
}
|
|
2281
2888
|
}
|
|
2282
2889
|
}
|
|
2283
2890
|
|
|
2284
|
-
private async
|
|
2891
|
+
private async addRelationValue(key: string, value: any, batchId?: string) {
|
|
2285
2892
|
// Phase 1: Use metadata instead of Prolog queries
|
|
2286
|
-
const metadata = this.
|
|
2893
|
+
const metadata = this.getRelationOptions(key);
|
|
2287
2894
|
if (!metadata) {
|
|
2288
|
-
console.warn(`
|
|
2895
|
+
console.warn(`Relation "${key}" has no metadata, skipping`);
|
|
2289
2896
|
return;
|
|
2290
2897
|
}
|
|
2291
2898
|
|
|
2292
2899
|
// Generate actions from metadata (replaces Prolog query)
|
|
2293
|
-
const actions = this.
|
|
2900
|
+
const actions = this.generateRelationAction(key, 'adder');
|
|
2294
2901
|
|
|
2295
2902
|
if (value != null) {
|
|
2296
2903
|
if (Array.isArray(value)) {
|
|
2297
2904
|
await Promise.all(
|
|
2298
2905
|
value.map((v) =>
|
|
2299
|
-
this
|
|
2906
|
+
this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(v) }], batchId)
|
|
2300
2907
|
)
|
|
2301
2908
|
);
|
|
2302
2909
|
} else {
|
|
2303
|
-
await this
|
|
2910
|
+
await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
|
|
2304
2911
|
}
|
|
2305
2912
|
}
|
|
2306
2913
|
}
|
|
2307
2914
|
|
|
2308
|
-
private async
|
|
2915
|
+
private async removeRelationValue(key: string, value: any, batchId?: string) {
|
|
2309
2916
|
// Phase 1: Use metadata instead of Prolog queries
|
|
2310
|
-
const metadata = this.
|
|
2917
|
+
const metadata = this.getRelationOptions(key);
|
|
2311
2918
|
if (!metadata) {
|
|
2312
|
-
console.warn(`
|
|
2919
|
+
console.warn(`Relation "${key}" has no metadata, skipping`);
|
|
2313
2920
|
return;
|
|
2314
2921
|
}
|
|
2315
2922
|
|
|
2316
2923
|
// Generate actions from metadata (replaces Prolog query)
|
|
2317
|
-
const actions = this.
|
|
2924
|
+
const actions = this.generateRelationAction(key, 'remover');
|
|
2318
2925
|
|
|
2319
2926
|
if (value != null) {
|
|
2320
2927
|
if (Array.isArray(value)) {
|
|
2321
2928
|
await Promise.all(
|
|
2322
2929
|
value.map((v) =>
|
|
2323
|
-
this
|
|
2930
|
+
this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(v) }], batchId)
|
|
2324
2931
|
)
|
|
2325
2932
|
);
|
|
2326
2933
|
} else {
|
|
2327
|
-
await this
|
|
2934
|
+
await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
|
|
2328
2935
|
}
|
|
2329
2936
|
}
|
|
2330
2937
|
}
|
|
2331
2938
|
|
|
2332
2939
|
/**
|
|
2333
2940
|
* Saves the model instance to the perspective.
|
|
2334
|
-
*
|
|
2941
|
+
*
|
|
2942
|
+
* **New instances** (no snapshot yet): creates the subject via
|
|
2943
|
+
* `createSubject` with initial scalar values, then sets relations
|
|
2944
|
+
* via `innerUpdate`.
|
|
2945
|
+
*
|
|
2946
|
+
* **Existing instances** (snapshot present, i.e. fetched via `get()`
|
|
2947
|
+
* or a query): updates only dirty fields via `innerUpdate`, then
|
|
2948
|
+
* refreshes from the perspective.
|
|
2335
2949
|
*
|
|
2336
2950
|
* @param batchId - Optional batch ID for batch operations
|
|
2337
2951
|
* @throws Will throw if instance creation, linking, or updating fails
|
|
2338
2952
|
*
|
|
2339
2953
|
* @example
|
|
2340
2954
|
* ```typescript
|
|
2955
|
+
* // Create
|
|
2341
2956
|
* const recipe = new Recipe(perspective);
|
|
2342
2957
|
* recipe.name = "Spaghetti";
|
|
2343
|
-
* recipe.ingredients = ["pasta", "tomato sauce"];
|
|
2344
2958
|
* await recipe.save();
|
|
2345
2959
|
*
|
|
2346
|
-
* //
|
|
2347
|
-
*
|
|
2348
|
-
* await recipe.save(
|
|
2349
|
-
* await perspective.commitBatch(batchId);
|
|
2960
|
+
* // Update
|
|
2961
|
+
* recipe.rating = 10;
|
|
2962
|
+
* await recipe.save();
|
|
2350
2963
|
* ```
|
|
2351
2964
|
*/
|
|
2352
2965
|
async save(batchId?: string) {
|
|
2353
|
-
//
|
|
2354
|
-
|
|
2966
|
+
// Existing instance → update path (has been fetched / hydrated before)
|
|
2967
|
+
if (this._snapshot) {
|
|
2968
|
+
await this.innerUpdate(true, batchId);
|
|
2969
|
+
if (batchId) {
|
|
2970
|
+
// Batch hasn't been committed yet — getData() would fetch stale data
|
|
2971
|
+
// and overwrite in-memory values. Just refresh the snapshot so further
|
|
2972
|
+
// saves within the same batch diff correctly.
|
|
2973
|
+
this.takeSnapshot();
|
|
2974
|
+
} else {
|
|
2975
|
+
await this.getData();
|
|
2976
|
+
}
|
|
2977
|
+
return;
|
|
2978
|
+
}
|
|
2355
2979
|
|
|
2980
|
+
// New instance → create path
|
|
2356
2981
|
let batchCreatedHere = false;
|
|
2357
2982
|
if(!batchId) {
|
|
2358
2983
|
batchId = await this.perspective.createBatch()
|
|
@@ -2360,48 +2985,72 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2360
2985
|
}
|
|
2361
2986
|
|
|
2362
2987
|
|
|
2363
|
-
//
|
|
2364
|
-
|
|
2365
|
-
|
|
2366
|
-
|
|
2367
|
-
|
|
2368
|
-
|
|
2369
|
-
|
|
2988
|
+
// Check if the model has any constructor actions (required properties,
|
|
2989
|
+
// flags, or properties with initial values). Models whose properties are
|
|
2990
|
+
// all optional, have no @Flag, and have no initial values produce an empty
|
|
2991
|
+
// SHACL constructor, so calling createSubject would fail on the Rust side
|
|
2992
|
+
// ("No SHACL constructor found"). In that case we skip createSubject
|
|
2993
|
+
// entirely and let innerUpdate write the links directly.
|
|
2994
|
+
const metadata = (this.constructor as typeof Ad4mModel).getModelMetadata();
|
|
2995
|
+
const hasConstructor = Object.values(metadata.properties).some(
|
|
2996
|
+
(p) => p.required || p.flag || p.initial !== undefined
|
|
2997
|
+
);
|
|
2370
2998
|
|
|
2371
|
-
|
|
2372
|
-
|
|
2999
|
+
if (hasConstructor) {
|
|
3000
|
+
// First filter out the properties that are not relations (arrays)
|
|
3001
|
+
const initialValues = {};
|
|
3002
|
+
for (const [key, value] of Object.entries(this)) {
|
|
3003
|
+
if (value !== undefined && value !== null && !(Array.isArray(value) && value.length > 0) && !value?.action) {
|
|
3004
|
+
initialValues[key] = value;
|
|
3005
|
+
}
|
|
3006
|
+
}
|
|
2373
3007
|
|
|
2374
|
-
|
|
2375
|
-
|
|
2376
|
-
className,
|
|
2377
|
-
this.#baseExpression,
|
|
2378
|
-
initialValues,
|
|
2379
|
-
batchId
|
|
2380
|
-
);
|
|
3008
|
+
// Get the class name instead of passing the instance to avoid Prolog query generation
|
|
3009
|
+
const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
|
|
2381
3010
|
|
|
2382
|
-
|
|
2383
|
-
|
|
2384
|
-
|
|
2385
|
-
|
|
2386
|
-
|
|
2387
|
-
|
|
3011
|
+
// Create the subject with the initial values
|
|
3012
|
+
await this.perspective.createSubject(
|
|
3013
|
+
className,
|
|
3014
|
+
this._baseExpression,
|
|
3015
|
+
initialValues,
|
|
3016
|
+
batchId
|
|
3017
|
+
);
|
|
3018
|
+
}
|
|
2388
3019
|
|
|
2389
|
-
// Set
|
|
2390
|
-
|
|
3020
|
+
// Set properties and relations via innerUpdate.
|
|
3021
|
+
// When createSubject was skipped (no constructor actions), we must enable
|
|
3022
|
+
// property writing so that scalar values are persisted as links.
|
|
3023
|
+
await this.innerUpdate(!hasConstructor, batchId)
|
|
2391
3024
|
|
|
2392
3025
|
// If we got a batchId passed in, we let the caller decide when to commit.
|
|
2393
|
-
//
|
|
2394
|
-
// until the
|
|
3026
|
+
// We can't call getData() since the instance won't exist in the perspective
|
|
3027
|
+
// until the batch is committed.
|
|
2395
3028
|
if (batchCreatedHere) {
|
|
2396
3029
|
await this.perspective.commitBatch(batchId)
|
|
2397
3030
|
await this.getData();
|
|
3031
|
+
} else {
|
|
3032
|
+
// Take a snapshot so that a subsequent save() within the same batch
|
|
3033
|
+
// routes through the UPDATE path instead of CREATE, avoiding duplicate
|
|
3034
|
+
// links (e.g. two competing "title" values).
|
|
3035
|
+
this.takeSnapshot();
|
|
2398
3036
|
}
|
|
2399
3037
|
}
|
|
2400
3038
|
|
|
2401
3039
|
private cleanCopy() {
|
|
2402
|
-
const
|
|
2403
|
-
const
|
|
2404
|
-
|
|
3040
|
+
const ctor = this.constructor as typeof Ad4mModel;
|
|
3041
|
+
const metadata = ctor.getModelMetadata();
|
|
3042
|
+
const cleanCopy: Record<string, any> = {};
|
|
3043
|
+
|
|
3044
|
+
// Only include schema-declared fields (properties + relations),
|
|
3045
|
+
// preserving internal ORM machinery (_id, _perspective, generated
|
|
3046
|
+
// addX/removeX/setX methods, _snapshot, etc.)
|
|
3047
|
+
const schemaFields = new Set([
|
|
3048
|
+
...Object.keys(metadata.properties),
|
|
3049
|
+
...Object.keys(metadata.relations),
|
|
3050
|
+
]);
|
|
3051
|
+
|
|
3052
|
+
for (const key of schemaFields) {
|
|
3053
|
+
const value = (this as any)[key];
|
|
2405
3054
|
if (value !== undefined && value !== null && key !== "author" && key !== "timestamp") {
|
|
2406
3055
|
cleanCopy[key] = value;
|
|
2407
3056
|
}
|
|
@@ -2410,37 +3059,60 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2410
3059
|
}
|
|
2411
3060
|
|
|
2412
3061
|
private async innerUpdate(setProperties: boolean = true, batchId?: string) {
|
|
2413
|
-
|
|
3062
|
+
const ctor = this.constructor as typeof Ad4mModel;
|
|
3063
|
+
this._subjectClassName = await this._perspective.stringOrTemplateObjectToSubjectClassName(this.cleanCopy());
|
|
3064
|
+
|
|
3065
|
+
// Determine which fields actually changed (skip unchanged when snapshot exists)
|
|
3066
|
+
const dirty = this._snapshot ? new Set(this.changedFields()) : null;
|
|
3067
|
+
|
|
3068
|
+
// Only iterate schema-declared fields, not internal ORM properties
|
|
3069
|
+
const metadata = ctor.getModelMetadata();
|
|
3070
|
+
const schemaFields = new Set([
|
|
3071
|
+
...Object.keys(metadata.properties),
|
|
3072
|
+
...Object.keys(metadata.relations),
|
|
3073
|
+
]);
|
|
2414
3074
|
|
|
2415
3075
|
const entries = Object.entries(this);
|
|
2416
3076
|
for (const [key, value] of entries) {
|
|
3077
|
+
// Only process schema-declared fields
|
|
3078
|
+
if (!schemaFields.has(key)) continue;
|
|
3079
|
+
// Skip unchanged fields when a snapshot is available
|
|
3080
|
+
if (dirty && !dirty.has(key)) continue;
|
|
3081
|
+
|
|
2417
3082
|
if (value !== undefined && value !== null) {
|
|
2418
3083
|
if (value?.action) {
|
|
2419
3084
|
switch (value.action) {
|
|
2420
3085
|
case "setter":
|
|
2421
|
-
await this.
|
|
3086
|
+
await this.setRelationValues(key, value.value, batchId);
|
|
2422
3087
|
break;
|
|
2423
3088
|
case "adder":
|
|
2424
|
-
await this.
|
|
3089
|
+
await this.addRelationValue(key, value.value, batchId);
|
|
2425
3090
|
break;
|
|
2426
3091
|
case "remover":
|
|
2427
|
-
await this.
|
|
3092
|
+
await this.removeRelationValue(key, value.value, batchId);
|
|
2428
3093
|
break;
|
|
2429
3094
|
default:
|
|
2430
|
-
await this.
|
|
3095
|
+
await this.setRelationValues(key, value.value, batchId);
|
|
2431
3096
|
break;
|
|
2432
3097
|
}
|
|
2433
3098
|
} else if (Array.isArray(value)) {
|
|
2434
|
-
// Handle all arrays as
|
|
2435
|
-
await this.
|
|
3099
|
+
// Handle all arrays as relations, including empty ones (which clears the relation)
|
|
3100
|
+
await this.setRelationValues(key, value, batchId);
|
|
2436
3101
|
} else if (value !== undefined && value !== null && value !== "") {
|
|
2437
3102
|
if (setProperties) {
|
|
2438
|
-
// Check if this is a
|
|
2439
|
-
const
|
|
2440
|
-
if (
|
|
2441
|
-
// Skip - it's a
|
|
3103
|
+
// Check if this is a relation property (has relation metadata)
|
|
3104
|
+
const relationMeta = this.getRelationOptions(key);
|
|
3105
|
+
if (relationMeta) {
|
|
3106
|
+
// Skip - it's a relation, not a regular property
|
|
2442
3107
|
continue;
|
|
2443
3108
|
}
|
|
3109
|
+
|
|
3110
|
+
// Skip flag properties — they are immutable after creation
|
|
3111
|
+
const propMeta = this.getPropertyMetadata(key);
|
|
3112
|
+
if (propMeta?.flag) {
|
|
3113
|
+
continue;
|
|
3114
|
+
}
|
|
3115
|
+
|
|
2444
3116
|
await this.setProperty(key, value, batchId);
|
|
2445
3117
|
}
|
|
2446
3118
|
}
|
|
@@ -2449,46 +3121,42 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2449
3121
|
}
|
|
2450
3122
|
|
|
2451
3123
|
/**
|
|
2452
|
-
*
|
|
2453
|
-
*
|
|
2454
|
-
* @param
|
|
2455
|
-
*
|
|
2456
|
-
*
|
|
2457
|
-
* @example
|
|
2458
|
-
* ```typescript
|
|
2459
|
-
* const recipe = await Recipe.findAll(perspective)[0];
|
|
2460
|
-
* recipe.rating = 5;
|
|
2461
|
-
* recipe.ingredients.push("garlic");
|
|
2462
|
-
* await recipe.update();
|
|
2463
|
-
*
|
|
2464
|
-
* // Or with batch operations:
|
|
2465
|
-
* const batchId = await perspective.createBatch();
|
|
2466
|
-
* await recipe.update(batchId);
|
|
2467
|
-
* await perspective.commitBatch(batchId);
|
|
2468
|
-
* ```
|
|
2469
|
-
*/
|
|
2470
|
-
async update(batchId?: string) {
|
|
2471
|
-
await this.innerUpdate(true, batchId);
|
|
2472
|
-
await this.getData();
|
|
2473
|
-
}
|
|
2474
|
-
|
|
2475
|
-
/**
|
|
2476
|
-
* Gets the model instance with all properties and collections populated.
|
|
2477
|
-
*
|
|
3124
|
+
* Gets the model instance with all properties and relations populated.
|
|
3125
|
+
*
|
|
3126
|
+
* @param optsOrInclude - Optional hydration options. Accepts two forms:
|
|
3127
|
+
* - `GetOptions` wrapper: `{ include: { comments: true }, properties: ['title'] }`
|
|
3128
|
+
* - `IncludeMap` shorthand: `{ comments: true }` (equivalent to `{ include: { comments: true } }`)
|
|
2478
3129
|
* @returns The populated model instance
|
|
2479
3130
|
* @throws Will throw if data retrieval fails
|
|
2480
|
-
*
|
|
3131
|
+
*
|
|
2481
3132
|
* @example
|
|
2482
3133
|
* ```typescript
|
|
2483
3134
|
* const recipe = new Recipe(perspective, existingId);
|
|
2484
3135
|
* await recipe.get();
|
|
2485
3136
|
* console.log(recipe.name, recipe.ingredients);
|
|
3137
|
+
*
|
|
3138
|
+
* // Shorthand — pass IncludeMap directly:
|
|
3139
|
+
* await recipe.get({ ingredients: true });
|
|
3140
|
+
*
|
|
3141
|
+
* // Full options — includes sparse fieldset:
|
|
3142
|
+
* await recipe.get({ include: { ingredients: true }, properties: ['name'] });
|
|
2486
3143
|
* ```
|
|
2487
3144
|
*/
|
|
2488
|
-
async get() {
|
|
2489
|
-
|
|
3145
|
+
async get(optsOrInclude?: GetOptions | IncludeMap) {
|
|
3146
|
+
// Normalise: if the caller passed a plain IncludeMap shorthand (no `include`
|
|
3147
|
+
// or `properties` key at the top level) wrap it in GetOptions automatically.
|
|
3148
|
+
let opts: GetOptions | undefined;
|
|
3149
|
+
if (!optsOrInclude) {
|
|
3150
|
+
opts = undefined;
|
|
3151
|
+
} else if ('include' in optsOrInclude || 'properties' in optsOrInclude) {
|
|
3152
|
+
opts = optsOrInclude as GetOptions;
|
|
3153
|
+
} else {
|
|
3154
|
+
opts = { include: optsOrInclude as IncludeMap };
|
|
3155
|
+
}
|
|
3156
|
+
|
|
3157
|
+
this._subjectClassName = await this._perspective.stringOrTemplateObjectToSubjectClassName(this.cleanCopy());
|
|
2490
3158
|
|
|
2491
|
-
return await this.getData();
|
|
3159
|
+
return await this.getData(opts);
|
|
2492
3160
|
}
|
|
2493
3161
|
|
|
2494
3162
|
/**
|
|
@@ -2509,7 +3177,262 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2509
3177
|
* ```
|
|
2510
3178
|
*/
|
|
2511
3179
|
async delete(batchId?: string) {
|
|
2512
|
-
|
|
3180
|
+
// Check if the model has a destructor (required properties, flags, or
|
|
3181
|
+
// properties with initial values). Models whose properties are all
|
|
3182
|
+
// optional, have no @Flag, and have no initial values produce an empty
|
|
3183
|
+
// SHACL destructor, so calling removeSubject would fail. In that case
|
|
3184
|
+
// we skip the destructor and just remove all outgoing links directly.
|
|
3185
|
+
const metadata = (this.constructor as typeof Ad4mModel).getModelMetadata();
|
|
3186
|
+
const hasDestructor = Object.values(metadata.properties).some(
|
|
3187
|
+
(p) => p.required || p.flag || p.initial !== undefined
|
|
3188
|
+
);
|
|
3189
|
+
|
|
3190
|
+
if (hasDestructor) {
|
|
3191
|
+
// Remove the subject itself (destructor actions)
|
|
3192
|
+
await this._perspective.removeSubject(this, this._baseExpression, batchId);
|
|
3193
|
+
} else {
|
|
3194
|
+
// No destructor — manually remove all outgoing links from this node
|
|
3195
|
+
try {
|
|
3196
|
+
const outgoingLinks = await this._perspective.get(new LinkQuery({ source: this._baseExpression }));
|
|
3197
|
+
if (outgoingLinks.length > 0) {
|
|
3198
|
+
await this._perspective.removeLinks(outgoingLinks, batchId);
|
|
3199
|
+
}
|
|
3200
|
+
} catch (e) {
|
|
3201
|
+
console.warn(`delete(): failed to remove outgoing links for ${this._baseExpression}:`, e);
|
|
3202
|
+
}
|
|
3203
|
+
}
|
|
3204
|
+
|
|
3205
|
+
// Clean up incoming links — remove any links that point **to** this instance
|
|
3206
|
+
try {
|
|
3207
|
+
const incomingLinks = await this._perspective.get(new LinkQuery({ target: this._baseExpression }));
|
|
3208
|
+
if (incomingLinks.length > 0) {
|
|
3209
|
+
await this._perspective.removeLinks(incomingLinks, batchId);
|
|
3210
|
+
}
|
|
3211
|
+
} catch (e) {
|
|
3212
|
+
// Non-fatal: the subject was already deleted; incoming link cleanup is best-effort
|
|
3213
|
+
console.warn(`delete(): failed to clean up incoming links for ${this._baseExpression}:`, e);
|
|
3214
|
+
}
|
|
3215
|
+
}
|
|
3216
|
+
|
|
3217
|
+
// ──────────────────────────────────────────────────────────
|
|
3218
|
+
// Static convenience methods
|
|
3219
|
+
// ──────────────────────────────────────────────────────────
|
|
3220
|
+
|
|
3221
|
+
/**
|
|
3222
|
+
* Options for `Ad4mModel.create()`.
|
|
3223
|
+
*/
|
|
3224
|
+
static readonly CreateOptions: undefined; // type-only anchor for JSDoc
|
|
3225
|
+
|
|
3226
|
+
/**
|
|
3227
|
+
* Creates and saves a new model instance in one step.
|
|
3228
|
+
*
|
|
3229
|
+
* @param perspective - The perspective to create the instance in
|
|
3230
|
+
* @param data - Property values to assign before saving
|
|
3231
|
+
* @param options - Optional settings:
|
|
3232
|
+
* - `parent` — a `ParentScope` (model form or raw form) whose `id` will
|
|
3233
|
+
* be used to create an incoming link from the parent to the new instance.
|
|
3234
|
+
* - `batchId` — an existing batch id; when provided the link write and
|
|
3235
|
+
* `save()` are added to the batch instead of committed immediately.
|
|
3236
|
+
* @returns The saved model instance
|
|
3237
|
+
*
|
|
3238
|
+
* @example
|
|
3239
|
+
* ```typescript
|
|
3240
|
+
* // Simple create
|
|
3241
|
+
* const recipe = await Recipe.create(perspective, {
|
|
3242
|
+
* name: "Spaghetti",
|
|
3243
|
+
* rating: 5,
|
|
3244
|
+
* });
|
|
3245
|
+
*
|
|
3246
|
+
* // Create under a parent (link auto-created)
|
|
3247
|
+
* const comment = await Comment.create(perspective, { text: "Great!" }, {
|
|
3248
|
+
* parent: { model: Post, id: postId },
|
|
3249
|
+
* });
|
|
3250
|
+
*
|
|
3251
|
+
* // Create inside a transaction
|
|
3252
|
+
* await Ad4mModel.transaction(perspective, async (tx) => {
|
|
3253
|
+
* await Recipe.create(perspective, { name: "Pasta" }, { batchId: tx.batchId });
|
|
3254
|
+
* });
|
|
3255
|
+
* ```
|
|
3256
|
+
*/
|
|
3257
|
+
static async create<T extends Ad4mModel>(
|
|
3258
|
+
this: typeof Ad4mModel & (new (...args: any[]) => T),
|
|
3259
|
+
perspective: PerspectiveProxy,
|
|
3260
|
+
data: Record<string, any> = {},
|
|
3261
|
+
options?: { parent?: ParentScope; batchId?: string },
|
|
3262
|
+
): Promise<T> {
|
|
3263
|
+
const instance = new this(perspective) as T;
|
|
3264
|
+
Object.assign(instance, data);
|
|
3265
|
+
|
|
3266
|
+
// When a parent scope is provided without a caller-supplied batch, open a
|
|
3267
|
+
// new batch ourselves so that the instance creation and the parent→child
|
|
3268
|
+
// link are committed atomically. If either step throws, commitBatch is
|
|
3269
|
+
// never reached and the batch is implicitly abandoned (rollback).
|
|
3270
|
+
if (options?.parent && !options?.batchId) {
|
|
3271
|
+
const batchId = await perspective.createBatch();
|
|
3272
|
+
await instance.save(batchId);
|
|
3273
|
+
const predicate = resolveParentPredicate(options.parent, this);
|
|
3274
|
+
const link = new Link({
|
|
3275
|
+
source: options.parent.id,
|
|
3276
|
+
predicate,
|
|
3277
|
+
target: instance.id,
|
|
3278
|
+
});
|
|
3279
|
+
await perspective.add(link, 'shared', batchId);
|
|
3280
|
+
await perspective.commitBatch(batchId);
|
|
3281
|
+
// Hydrate the instance now that the batch has been committed (mirrors the
|
|
3282
|
+
// behaviour of save() when it manages its own batch).
|
|
3283
|
+
await instance.get();
|
|
3284
|
+
return instance;
|
|
3285
|
+
}
|
|
3286
|
+
|
|
3287
|
+
await instance.save(options?.batchId);
|
|
3288
|
+
|
|
3289
|
+
// Create parent → child link if a parent scope was provided
|
|
3290
|
+
if (options?.parent) {
|
|
3291
|
+
const predicate = resolveParentPredicate(options.parent, this);
|
|
3292
|
+
const link = new Link({
|
|
3293
|
+
source: options.parent.id,
|
|
3294
|
+
predicate,
|
|
3295
|
+
target: instance.id,
|
|
3296
|
+
});
|
|
3297
|
+
await perspective.add(link, 'shared', options?.batchId);
|
|
3298
|
+
}
|
|
3299
|
+
|
|
3300
|
+
return instance;
|
|
3301
|
+
}
|
|
3302
|
+
|
|
3303
|
+
/**
|
|
3304
|
+
* Updates an existing model instance identified by `id`.
|
|
3305
|
+
*
|
|
3306
|
+
* Fetches the instance, applies the provided changes, calls `save()`,
|
|
3307
|
+
* and returns the refreshed instance.
|
|
3308
|
+
*
|
|
3309
|
+
* @param perspective - The perspective containing the instance
|
|
3310
|
+
* @param id - The expression URI of the instance to update
|
|
3311
|
+
* @param data - Property values to merge before saving
|
|
3312
|
+
* @returns The updated model instance
|
|
3313
|
+
*
|
|
3314
|
+
* @example
|
|
3315
|
+
* ```typescript
|
|
3316
|
+
* const recipe = await Recipe.update(perspective, recipeId, {
|
|
3317
|
+
* rating: 10,
|
|
3318
|
+
* });
|
|
3319
|
+
* ```
|
|
3320
|
+
*/
|
|
3321
|
+
static async update<T extends Ad4mModel>(
|
|
3322
|
+
this: typeof Ad4mModel & (new (...args: any[]) => T),
|
|
3323
|
+
perspective: PerspectiveProxy,
|
|
3324
|
+
id: string,
|
|
3325
|
+
data: Record<string, any>,
|
|
3326
|
+
): Promise<T> {
|
|
3327
|
+
const instance = new this(perspective, id) as T;
|
|
3328
|
+
await instance.get();
|
|
3329
|
+
Object.assign(instance, data);
|
|
3330
|
+
await instance.save();
|
|
3331
|
+
return instance;
|
|
3332
|
+
}
|
|
3333
|
+
|
|
3334
|
+
/**
|
|
3335
|
+
* Deletes an existing model instance identified by `id`.
|
|
3336
|
+
*
|
|
3337
|
+
* Also cleans up any incoming links that point to this instance.
|
|
3338
|
+
*
|
|
3339
|
+
* @param perspective - The perspective containing the instance
|
|
3340
|
+
* @param id - The expression URI of the instance to delete
|
|
3341
|
+
*
|
|
3342
|
+
* @example
|
|
3343
|
+
* ```typescript
|
|
3344
|
+
* await Recipe.delete(perspective, recipeId);
|
|
3345
|
+
* ```
|
|
3346
|
+
*
|
|
3347
|
+
* @deprecated Use the name `delete` — `remove` is preserved as an alias.
|
|
3348
|
+
*/
|
|
3349
|
+
static async remove(
|
|
3350
|
+
this: typeof Ad4mModel & (new (...args: any[]) => Ad4mModel),
|
|
3351
|
+
perspective: PerspectiveProxy,
|
|
3352
|
+
id: string,
|
|
3353
|
+
): Promise<void> {
|
|
3354
|
+
return this.delete(perspective, id);
|
|
3355
|
+
}
|
|
3356
|
+
|
|
3357
|
+
/**
|
|
3358
|
+
* Deletes an existing model instance identified by `id`.
|
|
3359
|
+
*
|
|
3360
|
+
* Also cleans up any incoming links that point to this instance.
|
|
3361
|
+
*
|
|
3362
|
+
* @param perspective - The perspective containing the instance
|
|
3363
|
+
* @param id - The expression URI of the instance to delete
|
|
3364
|
+
*
|
|
3365
|
+
* @example
|
|
3366
|
+
* ```typescript
|
|
3367
|
+
* await Recipe.delete(perspective, recipeId);
|
|
3368
|
+
* ```
|
|
3369
|
+
*/
|
|
3370
|
+
static async delete(
|
|
3371
|
+
this: typeof Ad4mModel & (new (...args: any[]) => Ad4mModel),
|
|
3372
|
+
perspective: PerspectiveProxy,
|
|
3373
|
+
id: string,
|
|
3374
|
+
): Promise<void> {
|
|
3375
|
+
const instance = new this(perspective, id);
|
|
3376
|
+
await instance.delete();
|
|
3377
|
+
}
|
|
3378
|
+
|
|
3379
|
+
/**
|
|
3380
|
+
* Registers this model's SHACL schema on the given perspective.
|
|
3381
|
+
*
|
|
3382
|
+
* This ensures the perspective knows about the model's shape
|
|
3383
|
+
* (properties, relations, constraints) so instances can be
|
|
3384
|
+
* created, queried, and validated.
|
|
3385
|
+
*
|
|
3386
|
+
* @param perspective - The perspective to register the model on
|
|
3387
|
+
*
|
|
3388
|
+
* @example
|
|
3389
|
+
* ```typescript
|
|
3390
|
+
* await Recipe.register(perspective);
|
|
3391
|
+
* // Now you can create / query Recipe instances on this perspective
|
|
3392
|
+
* ```
|
|
3393
|
+
*/
|
|
3394
|
+
static async register(
|
|
3395
|
+
this: typeof Ad4mModel,
|
|
3396
|
+
perspective: PerspectiveProxy,
|
|
3397
|
+
): Promise<void> {
|
|
3398
|
+
await perspective.ensureSDNASubjectClass(this);
|
|
3399
|
+
}
|
|
3400
|
+
|
|
3401
|
+
/**
|
|
3402
|
+
* Executes a set of model operations inside a single batch (transaction).
|
|
3403
|
+
*
|
|
3404
|
+
* All `save`, `update`, and `delete` calls made via the provided `batchId`
|
|
3405
|
+
* are buffered and flushed atomically when the callback completes.
|
|
3406
|
+
* If the callback throws, the batch is **not** committed, preventing
|
|
3407
|
+
* partial writes.
|
|
3408
|
+
*
|
|
3409
|
+
* @param perspective - The perspective to operate on
|
|
3410
|
+
* @param fn - Async callback that receives a `TransactionContext` object.
|
|
3411
|
+
* Pass `tx.batchId` to `save(tx.batchId)`, `update(tx.batchId)`,
|
|
3412
|
+
* `delete(tx.batchId)`, etc.
|
|
3413
|
+
* @returns The value returned by `fn`
|
|
3414
|
+
*
|
|
3415
|
+
* @example
|
|
3416
|
+
* ```typescript
|
|
3417
|
+
* await Ad4mModel.transaction(perspective, async (tx) => {
|
|
3418
|
+
* const recipe = new Recipe(perspective);
|
|
3419
|
+
* recipe.name = "Spaghetti";
|
|
3420
|
+
* await recipe.save(tx.batchId);
|
|
3421
|
+
*
|
|
3422
|
+
* const old = await Recipe.query(perspective).where({ name: "Stale" }).run();
|
|
3423
|
+
* for (const r of old) await r.delete(tx.batchId);
|
|
3424
|
+
* });
|
|
3425
|
+
* // All changes committed atomically here
|
|
3426
|
+
* ```
|
|
3427
|
+
*/
|
|
3428
|
+
static async transaction<R = void>(
|
|
3429
|
+
perspective: PerspectiveProxy,
|
|
3430
|
+
fn: (tx: { batchId: string }) => Promise<R>,
|
|
3431
|
+
): Promise<R> {
|
|
3432
|
+
const batchId = await perspective.createBatch();
|
|
3433
|
+
const result = await fn({ batchId });
|
|
3434
|
+
await perspective.commitBatch(batchId);
|
|
3435
|
+
return result;
|
|
2513
3436
|
}
|
|
2514
3437
|
|
|
2515
3438
|
/**
|
|
@@ -2615,9 +3538,9 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2615
3538
|
(DynamicModelClass as any).className = options.name;
|
|
2616
3539
|
(DynamicModelClass.prototype as any).className = options.name;
|
|
2617
3540
|
|
|
2618
|
-
// Generate properties and
|
|
3541
|
+
// Generate properties and relations metadata
|
|
2619
3542
|
const properties: any = {};
|
|
2620
|
-
const
|
|
3543
|
+
const relations: any = {};
|
|
2621
3544
|
|
|
2622
3545
|
if (schema.properties) {
|
|
2623
3546
|
for (const [propertyName, propertySchema] of Object.entries(schema.properties)) {
|
|
@@ -2627,9 +3550,9 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2627
3550
|
const isArray = isArrayType(propertySchema);
|
|
2628
3551
|
|
|
2629
3552
|
if (isArray) {
|
|
2630
|
-
// Handle arrays as
|
|
2631
|
-
// Store the singular form as the
|
|
2632
|
-
|
|
3553
|
+
// Handle arrays as relations
|
|
3554
|
+
// Store the singular form as the relation key since SDNA generation expects singular
|
|
3555
|
+
relations[propertyName] = {
|
|
2633
3556
|
through: predicate,
|
|
2634
3557
|
local: this.getPropertyOption(propertyName, propertySchema, options, 'local')
|
|
2635
3558
|
};
|
|
@@ -2641,10 +3564,10 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2641
3564
|
value: []
|
|
2642
3565
|
});
|
|
2643
3566
|
|
|
2644
|
-
// Add
|
|
3567
|
+
// Add relation methods
|
|
2645
3568
|
const adderName = `add${capitalize(propertyName)}`;
|
|
2646
3569
|
const removerName = `remove${capitalize(propertyName)}`;
|
|
2647
|
-
const setterName = `
|
|
3570
|
+
const setterName = `set${capitalize(propertyName)}`;
|
|
2648
3571
|
|
|
2649
3572
|
(DynamicModelClass.prototype as any)[adderName] = function() {
|
|
2650
3573
|
// Placeholder function for SDNA generation
|
|
@@ -2664,7 +3587,13 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2664
3587
|
resolveLanguage = options.resolveLanguage;
|
|
2665
3588
|
}
|
|
2666
3589
|
const local = this.getPropertyOption(propertyName, propertySchema, options, 'local');
|
|
2667
|
-
|
|
3590
|
+
// Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
|
|
3591
|
+
let readOnly = this.getPropertyOption(propertyName, propertySchema, options, 'readOnly');
|
|
3592
|
+
if (readOnly === undefined) {
|
|
3593
|
+
const xWritable = propertySchema["x-ad4m"]?.writable;
|
|
3594
|
+
readOnly = xWritable !== undefined ? !xWritable : false;
|
|
3595
|
+
}
|
|
3596
|
+
const writable = !readOnly;
|
|
2668
3597
|
let initial = this.getPropertyOption(propertyName, propertySchema, options, 'initial');
|
|
2669
3598
|
|
|
2670
3599
|
// Handle nested objects by serializing to JSON
|
|
@@ -2677,6 +3606,13 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2677
3606
|
if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
|
|
2678
3607
|
resolveLanguage = 'literal';
|
|
2679
3608
|
}
|
|
3609
|
+
|
|
3610
|
+
// Default resolveLanguage to 'literal' for all remaining property types,
|
|
3611
|
+
// matching the @Property decorator behaviour. Without this, string values
|
|
3612
|
+
// stored as literal:// URLs are returned unparsed.
|
|
3613
|
+
if (resolveLanguage === undefined || resolveLanguage === null) {
|
|
3614
|
+
resolveLanguage = 'literal';
|
|
3615
|
+
}
|
|
2680
3616
|
|
|
2681
3617
|
// If property is required, ensure it has an initial value
|
|
2682
3618
|
if (isRequired && !initial) {
|
|
@@ -2715,56 +3651,30 @@ WHERE ${whereConditions.join(' AND ')}
|
|
|
2715
3651
|
}
|
|
2716
3652
|
}
|
|
2717
3653
|
|
|
2718
|
-
//
|
|
2719
|
-
//
|
|
2720
|
-
|
|
3654
|
+
// No auto-flag generation — models with all-optional properties use
|
|
3655
|
+
// open-world structural matching. Consumers who need type discrimination
|
|
3656
|
+
// should add an explicit @Flag to their model definition.
|
|
2721
3657
|
|
|
2722
|
-
|
|
2723
|
-
|
|
2724
|
-
|
|
2725
|
-
|
|
2726
|
-
|
|
2727
|
-
|
|
2728
|
-
|
|
2729
|
-
|
|
2730
|
-
|
|
2731
|
-
|
|
2732
|
-
typeValue = `${scheme}://instance`;
|
|
2733
|
-
}
|
|
2734
|
-
} else {
|
|
2735
|
-
const path = namespace.replace(/\/+$/,'');
|
|
2736
|
-
typeValue = `${path}/instance`;
|
|
2737
|
-
}
|
|
2738
|
-
|
|
2739
|
-
properties['__ad4m_type'] = {
|
|
2740
|
-
through: typeProperty,
|
|
2741
|
-
required: true,
|
|
2742
|
-
writable: false,
|
|
2743
|
-
initial: typeValue,
|
|
2744
|
-
flag: true
|
|
2745
|
-
};
|
|
2746
|
-
|
|
2747
|
-
// Add the type property to the prototype
|
|
2748
|
-
Object.defineProperty(DynamicModelClass.prototype, '__ad4m_type', {
|
|
2749
|
-
configurable: true,
|
|
2750
|
-
writable: false,
|
|
2751
|
-
value: typeValue
|
|
3658
|
+
// Attach metadata to WeakMap registries
|
|
3659
|
+
for (const [propName, propMeta] of Object.entries(properties)) {
|
|
3660
|
+
setPropertyRegistryEntry(DynamicModelClass, propName, propMeta as any);
|
|
3661
|
+
}
|
|
3662
|
+
for (const [relName, relMeta] of Object.entries(relations)) {
|
|
3663
|
+
setRelationRegistryEntry(DynamicModelClass, relName, {
|
|
3664
|
+
predicate: (relMeta as any).through || "",
|
|
3665
|
+
kind: 'hasMany',
|
|
3666
|
+
...(( relMeta as any).getter !== undefined && { getter: (relMeta as any).getter }),
|
|
3667
|
+
...(( relMeta as any).local !== undefined && { local: (relMeta as any).local }),
|
|
2752
3668
|
});
|
|
2753
|
-
|
|
2754
|
-
console.warn(`No properties with initial values found. Added automatic type flag: ${typeProperty} = ${typeValue}`);
|
|
2755
3669
|
}
|
|
2756
3670
|
|
|
2757
|
-
// Attach metadata to prototype
|
|
2758
|
-
(DynamicModelClass.prototype as any).__properties = properties;
|
|
2759
|
-
(DynamicModelClass.prototype as any).__collections = collections;
|
|
2760
|
-
|
|
2761
3671
|
// Store the JSON schema and options on the prototype for potential fallback use by getModelMetadata()
|
|
2762
3672
|
(DynamicModelClass.prototype as any).__jsonSchema = schema;
|
|
2763
3673
|
(DynamicModelClass.prototype as any).__jsonSchemaOptions = options;
|
|
2764
3674
|
|
|
2765
|
-
// Apply the
|
|
2766
|
-
const
|
|
2767
|
-
|
|
3675
|
+
// Apply the Model decorator to set up the generateSDNA method
|
|
3676
|
+
const ModelDecorator = Model({ name: options.name });
|
|
3677
|
+
ModelDecorator(DynamicModelClass);
|
|
2768
3678
|
|
|
2769
3679
|
return DynamicModelClass as typeof Ad4mModel;
|
|
2770
3680
|
}
|
|
@@ -3029,18 +3939,76 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
3029
3939
|
}
|
|
3030
3940
|
|
|
3031
3941
|
/**
|
|
3032
|
-
*
|
|
3033
|
-
*
|
|
3034
|
-
*
|
|
3942
|
+
* Scopes the query to instances linked from a parent.
|
|
3943
|
+
*
|
|
3944
|
+
* The predicate is resolved in order of precedence:
|
|
3945
|
+
* 1. **Instance only** — the parent's constructor is used as the model
|
|
3946
|
+
* class; its relation metadata is scanned for a relation whose
|
|
3947
|
+
* `target()` matches the queried model class.
|
|
3948
|
+
* 2. **Instance + options with `field`** — direct field-name lookup on
|
|
3949
|
+
* the parent model's relation metadata (disambiguates when a parent
|
|
3950
|
+
* has multiple relations targeting the same child class).
|
|
3951
|
+
* 3. **String id + model class** — same metadata scan (or field lookup if
|
|
3952
|
+
* options include `field`).
|
|
3953
|
+
* 4. **String id + string predicate** — raw escape hatch, no metadata lookup.
|
|
3954
|
+
*
|
|
3955
|
+
* Passing a plain string id with no second argument throws because the
|
|
3956
|
+
* predicate cannot be resolved without a model class.
|
|
3957
|
+
*
|
|
3958
|
+
* @param idOrInstance - The parent's expression URI **or** an Ad4mModel instance
|
|
3959
|
+
* @param modelOrPredicate - A model class (predicate auto-resolved) **or** a raw predicate string
|
|
3960
|
+
* @param options - Optional settings: `field` for direct relation-name lookup
|
|
3035
3961
|
* @returns The query builder for chaining
|
|
3036
|
-
*
|
|
3962
|
+
*
|
|
3037
3963
|
* @example
|
|
3038
3964
|
* ```typescript
|
|
3039
|
-
*
|
|
3965
|
+
* // Instance — predicate auto-resolved from Cookbook's @HasMany(() => Recipe)
|
|
3966
|
+
* Recipe.query(perspective).parent(cookbook).get();
|
|
3967
|
+
*
|
|
3968
|
+
* // Instance + field — disambiguate when parent has multiple relations to same child
|
|
3969
|
+
* Recipe.query(perspective).parent(cookbook, { field: "recipes" }).get();
|
|
3970
|
+
*
|
|
3971
|
+
* // String id + model class
|
|
3972
|
+
* Recipe.query(perspective).parent(cookbookId, Cookbook).get();
|
|
3973
|
+
*
|
|
3974
|
+
* // String id + model class + field
|
|
3975
|
+
* Recipe.query(perspective).parent(cookbookId, Cookbook, { field: "recipes" }).get();
|
|
3976
|
+
*
|
|
3977
|
+
* // String id + raw predicate (escape hatch)
|
|
3978
|
+
* Recipe.query(perspective).parent(cookbookId, "cookbook://recipe").get();
|
|
3040
3979
|
* ```
|
|
3041
3980
|
*/
|
|
3042
|
-
|
|
3043
|
-
|
|
3981
|
+
parent(idOrInstance: string | Ad4mModel, modelOrPredicate?: typeof Ad4mModel | string | { field: string }, options?: { field?: string }): ModelQueryBuilder<T> {
|
|
3982
|
+
const id = typeof idOrInstance === 'string' ? idOrInstance : idOrInstance.id;
|
|
3983
|
+
|
|
3984
|
+
// Handle options-object as second arg: parent(instance, { field: "recipes" })
|
|
3985
|
+
if (typeof modelOrPredicate === 'object' && modelOrPredicate !== null && !('prototype' in modelOrPredicate)) {
|
|
3986
|
+
if (typeof idOrInstance === 'string') {
|
|
3987
|
+
throw new Error(
|
|
3988
|
+
'parent() called with a string id and options object requires a model class as second argument',
|
|
3989
|
+
);
|
|
3990
|
+
}
|
|
3991
|
+
const model = idOrInstance.constructor as typeof Ad4mModel;
|
|
3992
|
+
this.queryParams.parent = { id, model, field: (modelOrPredicate as { field: string }).field };
|
|
3993
|
+
return this;
|
|
3994
|
+
}
|
|
3995
|
+
|
|
3996
|
+
const field = options?.field;
|
|
3997
|
+
|
|
3998
|
+
if (typeof modelOrPredicate === 'string') {
|
|
3999
|
+
// Raw predicate string → raw form of ParentScope
|
|
4000
|
+
this.queryParams.parent = { id, predicate: modelOrPredicate };
|
|
4001
|
+
} else if (typeof modelOrPredicate === 'function') {
|
|
4002
|
+
// Model class → model form of ParentScope
|
|
4003
|
+
this.queryParams.parent = { id, model: modelOrPredicate, ...(field && { field }) };
|
|
4004
|
+
} else if (typeof idOrInstance !== 'string') {
|
|
4005
|
+
// Ad4mModel instance — derive model class from constructor
|
|
4006
|
+
this.queryParams.parent = { id, model: idOrInstance.constructor as typeof Ad4mModel, ...(field && { field }) };
|
|
4007
|
+
} else {
|
|
4008
|
+
throw new Error(
|
|
4009
|
+
'parent() called with a string id requires a second argument: either a model class or a predicate string',
|
|
4010
|
+
);
|
|
4011
|
+
}
|
|
3044
4012
|
return this;
|
|
3045
4013
|
}
|
|
3046
4014
|
|
|
@@ -3061,18 +4029,33 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
3061
4029
|
}
|
|
3062
4030
|
|
|
3063
4031
|
/**
|
|
3064
|
-
* Specifies which
|
|
3065
|
-
*
|
|
3066
|
-
*
|
|
4032
|
+
* Specifies which relations to eager-load (hydrate into model instances).
|
|
4033
|
+
*
|
|
4034
|
+
* Without `include`, relation fields contain raw expression URIs (strings).
|
|
4035
|
+
* With `include`, the URIs are resolved into fully-hydrated model instances
|
|
4036
|
+
* using the `target` class declared in the relation decorator.
|
|
4037
|
+
*
|
|
4038
|
+
* Supports nested includes for multi-level eager loading.
|
|
4039
|
+
*
|
|
4040
|
+
* @param map - An IncludeMap describing which relations to hydrate
|
|
3067
4041
|
* @returns The query builder for chaining
|
|
3068
|
-
*
|
|
4042
|
+
*
|
|
3069
4043
|
* @example
|
|
3070
4044
|
* ```typescript
|
|
3071
|
-
*
|
|
4045
|
+
* // Hydrate comments one level deep
|
|
4046
|
+
* const recipes = await Recipe.query(perspective)
|
|
4047
|
+
* .include({ comments: true })
|
|
4048
|
+
* .run();
|
|
4049
|
+
* // recipe.comments is now Comment[] (model instances), not string[]
|
|
4050
|
+
*
|
|
4051
|
+
* // Nested: hydrate comments AND each comment's author
|
|
4052
|
+
* const recipes = await Recipe.query(perspective)
|
|
4053
|
+
* .include({ comments: { author: true } })
|
|
4054
|
+
* .run();
|
|
3072
4055
|
* ```
|
|
3073
4056
|
*/
|
|
3074
|
-
|
|
3075
|
-
this.queryParams.
|
|
4057
|
+
include(map: IncludeMap): ModelQueryBuilder<T> {
|
|
4058
|
+
this.queryParams.include = map;
|
|
3076
4059
|
return this;
|
|
3077
4060
|
}
|
|
3078
4061
|
|
|
@@ -3124,17 +4107,38 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
3124
4107
|
* ```
|
|
3125
4108
|
*/
|
|
3126
4109
|
async get(): Promise<T[]> {
|
|
4110
|
+
let results: T[];
|
|
3127
4111
|
if (this.useSurrealDBFlag) {
|
|
3128
4112
|
const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
|
|
3129
4113
|
const result = await this.perspective.querySurrealDB(surrealQuery);
|
|
3130
|
-
|
|
3131
|
-
return results as T[];
|
|
4114
|
+
({ results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result) as { results: T[] });
|
|
3132
4115
|
} else {
|
|
3133
4116
|
const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
3134
4117
|
const result = await this.perspective.infer(query);
|
|
3135
|
-
|
|
3136
|
-
return results as T[];
|
|
4118
|
+
({ results } = await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, result) as { results: T[] });
|
|
3137
4119
|
}
|
|
4120
|
+
|
|
4121
|
+
return results;
|
|
4122
|
+
}
|
|
4123
|
+
|
|
4124
|
+
/**
|
|
4125
|
+
* Returns the first matching instance, or `null` if none match.
|
|
4126
|
+
*
|
|
4127
|
+
* Internally sets `limit: 1` and delegates to `get()`.
|
|
4128
|
+
*
|
|
4129
|
+
* @returns The first matching instance, or `null`
|
|
4130
|
+
*
|
|
4131
|
+
* @example
|
|
4132
|
+
* ```typescript
|
|
4133
|
+
* const recipe = await Recipe.query(perspective)
|
|
4134
|
+
* .where({ name: "Pasta" })
|
|
4135
|
+
* .first();
|
|
4136
|
+
* ```
|
|
4137
|
+
*/
|
|
4138
|
+
async first(): Promise<T | null> {
|
|
4139
|
+
this.queryParams.limit = 1;
|
|
4140
|
+
const results = await this.get();
|
|
4141
|
+
return results[0] ?? null;
|
|
3138
4142
|
}
|
|
3139
4143
|
|
|
3140
4144
|
/**
|
|
@@ -3172,43 +4176,45 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
3172
4176
|
// Clean up any existing subscription
|
|
3173
4177
|
this.dispose();
|
|
3174
4178
|
|
|
4179
|
+
const ctor = this.ctor;
|
|
4180
|
+
|
|
3175
4181
|
if (this.useSurrealDBFlag) {
|
|
3176
|
-
const surrealQuery = await
|
|
4182
|
+
const surrealQuery = await ctor.queryToSurrealQL(this.perspective, this.queryParams);
|
|
3177
4183
|
this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
|
|
3178
4184
|
|
|
3179
4185
|
const processResults = async (result: any) => {
|
|
3180
|
-
|
|
3181
|
-
// is the new full set of results (because we re-query in Rust).
|
|
3182
|
-
// So we just need to map it to instances.
|
|
3183
|
-
const { results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
|
|
4186
|
+
const { results } = await ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
|
|
3184
4187
|
callback(results as T[]);
|
|
3185
4188
|
};
|
|
3186
4189
|
|
|
3187
4190
|
this.currentSubscription.onResult(processResults);
|
|
3188
4191
|
|
|
3189
4192
|
// Process initial result
|
|
3190
|
-
const { results } = await
|
|
4193
|
+
const { results } = await ctor.instancesFromSurrealResult(
|
|
3191
4194
|
this.perspective,
|
|
3192
4195
|
this.queryParams,
|
|
3193
4196
|
this.currentSubscription.result
|
|
3194
4197
|
);
|
|
4198
|
+
// Also invoke callback with initial results so subscribers see them
|
|
4199
|
+
callback(results as T[]);
|
|
3195
4200
|
return results as T[];
|
|
3196
4201
|
} else {
|
|
3197
|
-
|
|
3198
|
-
const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
4202
|
+
const query = await ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
3199
4203
|
this.currentSubscription = await this.perspective.subscribeInfer(query);
|
|
3200
4204
|
|
|
3201
4205
|
const processResults = async (result: AllInstancesResult) => {
|
|
3202
|
-
const { results } = await
|
|
4206
|
+
const { results } = await ctor.instancesFromPrologResult(this.perspective, this.queryParams, result);
|
|
3203
4207
|
callback(results as T[]);
|
|
3204
4208
|
};
|
|
3205
4209
|
|
|
3206
4210
|
this.currentSubscription.onResult(processResults);
|
|
3207
|
-
const { results } = await
|
|
4211
|
+
const { results } = await ctor.instancesFromPrologResult(
|
|
3208
4212
|
this.perspective,
|
|
3209
4213
|
this.queryParams,
|
|
3210
4214
|
this.currentSubscription.result
|
|
3211
4215
|
);
|
|
4216
|
+
// Also invoke callback with initial results so subscribers see them
|
|
4217
|
+
callback(results as T[]);
|
|
3212
4218
|
return results as T[];
|
|
3213
4219
|
}
|
|
3214
4220
|
}
|
|
@@ -3291,6 +4297,7 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
3291
4297
|
this.queryParams,
|
|
3292
4298
|
this.currentSubscription.result
|
|
3293
4299
|
);
|
|
4300
|
+
callback(totalCount);
|
|
3294
4301
|
return totalCount;
|
|
3295
4302
|
} else {
|
|
3296
4303
|
const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
@@ -3302,7 +4309,9 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
3302
4309
|
};
|
|
3303
4310
|
|
|
3304
4311
|
this.currentSubscription.onResult(processResults);
|
|
3305
|
-
|
|
4312
|
+
const initialCount = this.currentSubscription.result?.[0]?.TotalCount || 0;
|
|
4313
|
+
callback(initialCount);
|
|
4314
|
+
return initialCount;
|
|
3306
4315
|
}
|
|
3307
4316
|
}
|
|
3308
4317
|
|
|
@@ -3390,7 +4399,9 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
3390
4399
|
|
|
3391
4400
|
this.currentSubscription.onResult(processResults);
|
|
3392
4401
|
const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
|
|
3393
|
-
|
|
4402
|
+
const initialPage = { results, totalCount, pageSize, pageNumber };
|
|
4403
|
+
callback(initialPage);
|
|
4404
|
+
return initialPage;
|
|
3394
4405
|
} else {
|
|
3395
4406
|
const prologQuery = await this.ctor.queryToProlog(this.perspective, paginationQuery, this.modelClassName);
|
|
3396
4407
|
this.currentSubscription = await this.perspective.subscribeInfer(prologQuery);
|
|
@@ -3402,7 +4413,142 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
3402
4413
|
|
|
3403
4414
|
this.currentSubscription.onResult(processResults);
|
|
3404
4415
|
const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
|
|
3405
|
-
|
|
4416
|
+
const initialPrologPage = { results, totalCount, pageSize, pageNumber };
|
|
4417
|
+
callback(initialPrologPage);
|
|
4418
|
+
return initialPrologPage;
|
|
4419
|
+
}
|
|
4420
|
+
}
|
|
4421
|
+
}
|
|
4422
|
+
|
|
4423
|
+
// ── Standalone Prolog fact generator ──────────────────────────────────────────
|
|
4424
|
+
|
|
4425
|
+
/**
|
|
4426
|
+
* Convert a camelCase or PascalCase identifier to snake_case.
|
|
4427
|
+
* Examples: "TestPost" -> "test_post", "createdAt" -> "created_at"
|
|
4428
|
+
*/
|
|
4429
|
+
function toSnakeCase(str: string): string {
|
|
4430
|
+
return str
|
|
4431
|
+
.replace(/([A-Z])/g, "_$1")
|
|
4432
|
+
.toLowerCase()
|
|
4433
|
+
.replace(/^_/, "");
|
|
4434
|
+
}
|
|
4435
|
+
|
|
4436
|
+
function buildInstanceClause(predicateName: string, metadata: ModelMetadata): string | null {
|
|
4437
|
+
const props = metadata.properties;
|
|
4438
|
+
// Collect flags first — these are the strongest recognizers
|
|
4439
|
+
const flags = Object.values(props).filter((p) => p.flag && p.predicate && p.initial);
|
|
4440
|
+
if (flags.length > 0) {
|
|
4441
|
+
const conditions = flags
|
|
4442
|
+
.map((p) => `triple(X, '${p.predicate}', '${p.initial}')`)
|
|
4443
|
+
.join(",\n ");
|
|
4444
|
+
return `${predicateName}(X) :-\n ${conditions}.`;
|
|
4445
|
+
}
|
|
4446
|
+
// Fallback: required non-flag properties
|
|
4447
|
+
const required = Object.values(props).filter((p) => p.required && p.predicate && !p.flag);
|
|
4448
|
+
if (required.length > 0) {
|
|
4449
|
+
const conditions = required
|
|
4450
|
+
.map((p) => `triple(X, '${p.predicate}', _)`)
|
|
4451
|
+
.join(",\n ");
|
|
4452
|
+
return `${predicateName}(X) :-\n ${conditions}.`;
|
|
4453
|
+
}
|
|
4454
|
+
// Open-world structural fallback: match nodes that have at least one of the
|
|
4455
|
+
// model's declared property predicates. Uses disjunction (;) so any single
|
|
4456
|
+
// predicate is enough.
|
|
4457
|
+
const allPredicates = Object.values(props)
|
|
4458
|
+
.filter((p) => p.predicate)
|
|
4459
|
+
.map((p) => p.predicate!);
|
|
4460
|
+
if (metadata.relations) {
|
|
4461
|
+
for (const rel of Object.values(metadata.relations)) {
|
|
4462
|
+
if (rel.predicate) allPredicates.push(rel.predicate);
|
|
3406
4463
|
}
|
|
3407
4464
|
}
|
|
4465
|
+
if (allPredicates.length > 0) {
|
|
4466
|
+
const disjunction = allPredicates
|
|
4467
|
+
.map((pred) => `triple(X, '${pred}', _)`)
|
|
4468
|
+
.join(" ;\n ");
|
|
4469
|
+
return `${predicateName}(X) :-\n (${disjunction}).`;
|
|
4470
|
+
}
|
|
4471
|
+
return null;
|
|
4472
|
+
}
|
|
4473
|
+
|
|
4474
|
+
function buildPropertyClause(modelPredicateName: string, prop: PropertyMetadata): string | null {
|
|
4475
|
+
if (prop.flag) return null;
|
|
4476
|
+
if (!prop.predicate) return null;
|
|
4477
|
+
const clauseName = `${modelPredicateName}_${toSnakeCase(prop.name)}`;
|
|
4478
|
+
return `${clauseName}(X, Value) :- triple(X, '${prop.predicate}', Value).`;
|
|
4479
|
+
}
|
|
4480
|
+
|
|
4481
|
+
function buildRelationClause(modelPredicateName: string, relation: RelationMetadata): string | null {
|
|
4482
|
+
if (!relation.predicate) return null;
|
|
4483
|
+
const clauseName = `${modelPredicateName}_${toSnakeCase(relation.name)}`;
|
|
4484
|
+
if (relation.direction === "reverse") {
|
|
4485
|
+
return `${clauseName}(X, Values) :- findall(V, triple(V, '${relation.predicate}', X), Values).`;
|
|
4486
|
+
}
|
|
4487
|
+
return `${clauseName}(X, Values) :- findall(V, triple(X, '${relation.predicate}', V), Values).`;
|
|
4488
|
+
}
|
|
4489
|
+
|
|
4490
|
+
/**
|
|
4491
|
+
* Generate Prolog predicate facts from a model class's decorator metadata.
|
|
4492
|
+
*
|
|
4493
|
+
* Given a model class decorated with `@Model` (and its `@Flag`, `@Property`,
|
|
4494
|
+
* `@HasMany`, `@BelongsToMany` decorators), this function emits a string of
|
|
4495
|
+
* Prolog clauses that can be prepended to any `perspective.infer()` call.
|
|
4496
|
+
*
|
|
4497
|
+
* The generated predicates are:
|
|
4498
|
+
* - **Instance recognizer** — `modelName(X)` — matches instances of the model
|
|
4499
|
+
* - **Property getters** — `modelName_propName(X, Value)` — one per property
|
|
4500
|
+
* - **Relation getters** — `modelName_relName(X, Values)` — one per relation
|
|
4501
|
+
*
|
|
4502
|
+
* @example
|
|
4503
|
+
* ```typescript
|
|
4504
|
+
* import { generatePrologFacts } from '@coasys/ad4m';
|
|
4505
|
+
*
|
|
4506
|
+
* const facts = generatePrologFacts(Poll);
|
|
4507
|
+
* const result = await perspective.infer(\`
|
|
4508
|
+
* \${facts}
|
|
4509
|
+
* recent_popular_poll(X) :-
|
|
4510
|
+
* poll(X),
|
|
4511
|
+
* poll_vote_count(X, N), N > 10.
|
|
4512
|
+
* \`);
|
|
4513
|
+
* ```
|
|
4514
|
+
*
|
|
4515
|
+
* @param ModelClass - A class decorated with `@Model` that extends `Ad4mModel`
|
|
4516
|
+
* @returns A multi-line Prolog string ready for use with `perspective.infer()`
|
|
4517
|
+
*/
|
|
4518
|
+
export function generatePrologFacts(ModelClass: typeof Ad4mModel): string {
|
|
4519
|
+
const metadata = ModelClass.getModelMetadata();
|
|
4520
|
+
const predicateName = toSnakeCase(metadata.className);
|
|
4521
|
+
const lines: string[] = [];
|
|
4522
|
+
|
|
4523
|
+
lines.push(`% ${metadata.className} — generated Prolog facts`);
|
|
4524
|
+
|
|
4525
|
+
// Instance recognizer
|
|
4526
|
+
const instanceClause = buildInstanceClause(predicateName, metadata);
|
|
4527
|
+
if (instanceClause) {
|
|
4528
|
+
lines.push("");
|
|
4529
|
+
lines.push(`% Instance recognizer`);
|
|
4530
|
+
lines.push(instanceClause);
|
|
4531
|
+
}
|
|
4532
|
+
|
|
4533
|
+
// Property getters
|
|
4534
|
+
const propClauses = Object.values(metadata.properties)
|
|
4535
|
+
.map((p) => buildPropertyClause(predicateName, p))
|
|
4536
|
+
.filter((c): c is string => c !== null);
|
|
4537
|
+
if (propClauses.length > 0) {
|
|
4538
|
+
lines.push("");
|
|
4539
|
+
lines.push(`% Field getters`);
|
|
4540
|
+
lines.push(...propClauses);
|
|
4541
|
+
}
|
|
4542
|
+
|
|
4543
|
+
// Relation getters
|
|
4544
|
+
const relClauses = Object.values(metadata.relations)
|
|
4545
|
+
.map((c) => buildRelationClause(predicateName, c))
|
|
4546
|
+
.filter((c): c is string => c !== null);
|
|
4547
|
+
if (relClauses.length > 0) {
|
|
4548
|
+
lines.push("");
|
|
4549
|
+
lines.push(`% Relation getters`);
|
|
4550
|
+
lines.push(...relClauses);
|
|
4551
|
+
}
|
|
4552
|
+
|
|
4553
|
+
return lines.join("\n");
|
|
3408
4554
|
}
|