@coasys/ad4m 0.13.0-test-2 → 0.13.0-test-3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/lib/index.cjs +1060 -147
  2. package/lib/index.js +1054 -147
  3. package/lib/src/index.d.ts +0 -1
  4. package/lib/src/index.js +0 -1
  5. package/lib/src/language/Language.d.ts +26 -214
  6. package/lib/src/language/Language.js +28 -2
  7. package/lib/src/model/Ad4mModel.d.ts +25 -1
  8. package/lib/src/model/Ad4mModel.js +139 -30
  9. package/lib/src/model/Ad4mModel.test.js +214 -32
  10. package/lib/src/model/ModelQueryBuilder.d.ts +19 -0
  11. package/lib/src/model/ModelQueryBuilder.js +62 -18
  12. package/lib/src/model/hydration-batching.test.d.ts +7 -0
  13. package/lib/src/model/hydration-batching.test.js +456 -0
  14. package/lib/src/model/hydration.d.ts +1 -0
  15. package/lib/src/model/hydration.js +279 -70
  16. package/lib/src/model/query-sparql.d.ts +78 -1
  17. package/lib/src/model/query-sparql.js +447 -16
  18. package/lib/src/model/query-sparql.test.d.ts +1 -0
  19. package/lib/src/model/query-sparql.test.js +495 -0
  20. package/lib/src/model/query-utils.js +4 -0
  21. package/lib/src/model/subscription-delta.test.d.ts +24 -0
  22. package/lib/src/model/subscription-delta.test.js +180 -0
  23. package/lib/src/model/subscription-pool.js +48 -2
  24. package/lib/src/model/types.d.ts +49 -1
  25. package/lib/src/perspectives/PerspectiveClient.d.ts +2 -0
  26. package/lib/src/perspectives/PerspectiveClient.js +37 -9
  27. package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
  28. package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
  29. package/lib/src/perspectives/PerspectiveProxy.d.ts +3 -0
  30. package/lib/src/perspectives/PerspectiveProxy.js +15 -0
  31. package/package.json +1 -1
  32. package/src/Ad4mClient.test.ts +56 -1
  33. package/src/index.ts +0 -1
  34. package/src/language/Language.ts +54 -275
  35. package/src/model/Ad4mModel.test.ts +222 -35
  36. package/src/model/Ad4mModel.ts +144 -30
  37. package/src/model/ModelQueryBuilder.ts +66 -18
  38. package/src/model/hydration-batching.test.ts +563 -0
  39. package/src/model/hydration.ts +249 -47
  40. package/src/model/query-sparql.test.ts +568 -0
  41. package/src/model/query-sparql.ts +473 -16
  42. package/src/model/query-utils.ts +4 -0
  43. package/src/model/subscription-delta.test.ts +207 -0
  44. package/src/model/subscription-pool.ts +50 -2
  45. package/src/model/types.ts +50 -1
  46. package/src/perspectives/PerspectiveClient.test.ts +204 -0
  47. package/src/perspectives/PerspectiveClient.ts +36 -7
  48. package/src/perspectives/PerspectiveProxy.ts +18 -0
  49. package/lib/src/model/query-surreal.d.ts +0 -44
  50. package/lib/src/model/query-surreal.js +0 -249
  51. package/lib/src/model/surreal-utils.d.ts +0 -42
  52. package/lib/src/model/surreal-utils.js +0 -128
  53. package/src/language/LanguageContext.ts +0 -37
  54. package/tsconfig-browser.json +0 -82
@@ -8,7 +8,6 @@ export * from "./expression/ExpressionRef";
8
8
  export * from "./language/Icon";
9
9
  export * from "./language/Language";
10
10
  export * from "./language/LanguageRef";
11
- export * from "./language/LanguageContext";
12
11
  export * from "./language/LanguageHandle";
13
12
  export * from "./language/LanguageMeta";
14
13
  export * from "./links/Links";
package/lib/src/index.js CHANGED
@@ -8,7 +8,6 @@ export * from "./expression/ExpressionRef";
8
8
  export * from "./language/Icon";
9
9
  export * from "./language/Language";
10
10
  export * from "./language/LanguageRef";
11
- export * from "./language/LanguageContext";
12
11
  export * from "./language/LanguageHandle";
13
12
  export * from "./language/LanguageMeta";
14
13
  export * from "./links/Links";
@@ -1,181 +1,23 @@
1
- import type { Address } from '../Address';
2
- import { DID } from '../DID';
3
- import type { Expression } from '../expression/Expression';
4
- import { Perspective, PerspectiveExpression } from '../perspectives/Perspective';
5
- import { PerspectiveDiff } from '../perspectives/PerspectiveDiff';
6
- import { PerspectiveState } from '../perspectives/PerspectiveHandle';
7
- import { LinkQuery } from '../perspectives/LinkQuery';
8
- /** Interface of AD4M Languages
1
+ import { DID } from "../DID";
2
+ import { PerspectiveExpression } from "../perspectives/Perspective";
3
+ /**
4
+ * # AD4M Language — client-side types
9
5
  *
10
- * Any JavaScript module that implements a create() function that returns an object that implements this interface
11
- * is a valid AD4M language.
12
- * So the AD4M-internal representation of a language is an object that implements this interface.
6
+ * This file only contains the client-visible types that the AD4M GraphQL
7
+ * API exposes on top of a running Language — interaction metadata, online
8
+ * agent records, and the telepresence-signal callback shape.
13
9
  *
14
- * Since there are a few different kinds of languages, this interface is split into optional sub-interfaces.
15
- * The only required property is the name of the language.
10
+ * **If you're authoring an AD4M Language**, you don't consume types from
11
+ * here — use [`@coasys/ad4m-ldk`](https://www.npmjs.com/package/@coasys/ad4m-ldk)
12
+ * (or the [Rust ALDK](https://crates.io/crates/ad4m-ldk)), which provide
13
+ * the capability traits, typed runtime-import wrappers, and authoring
14
+ * macros/helpers.
16
15
  *
17
- * The most usual kind of language is the "Expression Language", which is a language that can be used to create
18
- * and share Expressions.
19
- * For that, implement the expressionsAdapter and expressionUI interface.
20
- *
21
- * The second most common kind of language is the "Link Language", which is a language that builds the core
22
- * of AD4M Neighbourhoods.
23
- * For that, implement the linksAdapter interface.
24
- */
25
- export interface Language {
26
- readonly name: string;
27
- /** Flagging expressions as immutable to enable
28
- * expression caching in the ad4m-executor
29
- */
30
- isImmutableExpression?(expression: Address): boolean;
31
- /** ExpressionAdapter implements means of getting an Expression
32
- * by address and putting an expression
33
- */
34
- readonly expressionAdapter?: ExpressionAdapter;
35
- /** Interface for getting UI/web components for rendering Expressions of this Language */
36
- readonly expressionUI?: ExpressionUI;
37
- /** Interface of LinkLanguages for the core implementation of Neighbourhoods */
38
- readonly perspectiveSyncAdapter?: PerspectiveSyncAdapter;
39
- /** Interface for Languages that implement a query return a Perspective (snapshot)
40
- * Used for back-links and wrapping of APIs that implement queries.
41
- */
42
- readonly pespectiveQueryAdapter?: PerspectiveQueryAdapter;
43
- /** Additional Interface of LinkLanguages that support telepresence features,
44
- * that is:
45
- * - seeing who is online and getting a status
46
- * - sending/receiveing p2p signals to other online agents without affecting
47
- * the shared Perspective of the Neighbourhood
48
- * (see TelepresenceAdapter for more details)
49
- */
50
- readonly telepresenceAdapter?: TelepresenceAdapter;
51
- /** Implementation of a Language that defines and stores Languages*/
52
- readonly languageAdapter?: LanguageAdapter;
53
- /** Optional adapter for getting Expressions by author */
54
- readonly getByAuthorAdapter?: GetByAuthorAdapter;
55
- /** Optional adapter for getting all Expressions */
56
- readonly getAllAdapter?: GetAllAdapter;
57
- /** Optional adapter for direct messaging between agents */
58
- readonly directMessageAdapter?: DirectMessageAdapter;
59
- /** Interface for providing UI components for the settings of this Language */
60
- readonly settingsUI?: SettingsUI;
61
- /** Optional function to make any cleanup/teardown if your language gets deleting in the ad4m-executor */
62
- readonly teardown?: () => void;
63
- /** All available interactions this agent could execute on given expression */
64
- interactions(expression: Address): Interaction[];
65
- }
66
- /** UI factories returning web components */
67
- export interface ExpressionUI {
68
- /** Returns JS code of a web component that renders the given expression */
69
- icon(): string;
70
- /** Returns JS code of a web component used to create new expressions */
71
- constructorIcon(): string;
72
- }
73
- export interface SettingsUI {
74
- settingsIcon(): string;
75
- }
76
- /** Interface for the most common Expression Languages */
77
- export interface ExpressionAdapter {
78
- /** Returns an Expression by address, or null if there is no Expression
79
- * with that given address
80
- */
81
- get(address: Address): Promise<Expression | null>;
82
- /** Strategy for putting an expression with needs to be different
83
- * for those two cases:
84
- * 1. PublicSharing means that this language supports the creation
85
- * and sharing of Expressions, which is the common use-case
86
- * 2. ReadOnlyLanguage means that the Language implements a pre-defined
87
- * set of expressions (which can be infinite or finite).
88
- * For example the url-iframe Language which directly maps URLs to
89
- * addresses - meaning every well formed URL is an address in this
90
- * Language. Or a potential Language implementing the verbs/predicates
91
- * of a spec like FOAF.
92
- */
93
- putAdapter: PublicSharing | ReadOnlyLanguage;
94
- }
95
- /** Implement this interface if your Language supports creation of sharing
96
- * of Expressions.
97
- * See ExpressionAdapter
98
- */
99
- export interface PublicSharing {
100
- /** Create an Expression and shares it.
101
- * Return the Expression's address.
102
- * @param content is the object created by the constructorIcon component
103
- */
104
- createPublic(content: object): Promise<Address>;
105
- }
106
- /** Implement this interface if your Language is defined over a static
107
- * set of pre-defined Expressions.
108
- */
109
- export interface ReadOnlyLanguage {
110
- /** This just calculates the address of an object
111
- * @param content is the object created by the constructorIcon component
112
- */
113
- addressOf(content: object): Promise<Address>;
114
- }
115
- export interface LanguageAdapter {
116
- getLanguageSource(address: Address): Promise<string>;
117
- }
118
- export interface GetByAuthorAdapter {
119
- getByAuthor(author: DID, count: number, page: number): Promise<Expression[] | null>;
120
- }
121
- export interface GetAllAdapter {
122
- getAll(filter: any, count: number, page: number): Promise<Expression[] | null>;
123
- }
124
- export type PerspectiveDiffObserver = (diff: PerspectiveDiff) => void;
125
- export type SyncStateChangeObserver = (state: PerspectiveState) => void;
126
- /** Interface for "Link Languages" that facilitate the synchronization
127
- * between agents' local Perspectives inside a Neighbourhood.
128
- * The assumption is that every version of the shared Perspective
129
- * is labeled with a unique revision string.
130
- * Changes are committed and retrieved through diffs.
131
- * Think of a PerspectiveSyncAdapter as a git branch to which agents commit
132
- * their changes to and pull diffs from their current revision
133
- * to the latest one.
16
+ * The normative interface definition lives in
17
+ * [`docs-src/ad4m-lang.wit`](https://github.com/coasys/ad4m/blob/dev/docs-src/ad4m-lang.wit).
18
+ * The prose spec is
19
+ * [`docs-src/language-interface-spec.md`](https://github.com/coasys/ad4m/blob/dev/docs-src/language-interface-spec.md).
134
20
  */
135
- export interface PerspectiveSyncAdapter {
136
- writable(): boolean;
137
- public(): boolean;
138
- others(): Promise<DID[]>;
139
- /** What revision are we on now -> what changes are included in output of render() */
140
- currentRevision(): Promise<string>;
141
- /**
142
- * Check for and get new changes,
143
- * notify others of local changes.
144
- * This function will be called every
145
- * few seconds by the ad4m-executor.
146
- * */
147
- sync(): Promise<PerspectiveDiff>;
148
- /** Returns the full, rendered Perspective at currentRevision */
149
- render(): Promise<Perspective>;
150
- /** Publish changes */
151
- commit(diff: PerspectiveDiff): Promise<string>;
152
- /** Get push notification when a diff got published */
153
- addCallback(callback: PerspectiveDiffObserver): any;
154
- /** Add a sync state callback method */
155
- addSyncStateChangeCallback(callback: SyncStateChangeObserver): any;
156
- /**
157
- * Set the local agents (DIDs) that own this perspective/neighbourhood.
158
- * This is used to determine which agents should be registered in the DHT.
159
- * Optional - if not implemented, all local agents may be registered.
160
- *
161
- * This is a temporary hack to support multiple users on one node joining the same neighbourhood.
162
- * Once we migrate the LanguageController to Rust and run Languages per user, each user will get their
163
- * own language instance and we won't need to explicitly set local agents. This will provide better
164
- * isolation and avoid the need to share language state between users.
165
- */
166
- setLocalAgents?(agents: DID[]): void;
167
- }
168
- export type MessageCallback = (message: PerspectiveExpression) => void;
169
- export type StatusCallback = (caller: DID) => Perspective;
170
- export interface DirectMessageAdapter {
171
- recipient(): DID;
172
- status(): Promise<PerspectiveExpression | void>;
173
- sendP2P(message: Perspective): Promise<PerspectiveExpression | void>;
174
- sendInbox(message: Perspective): Promise<PerspectiveExpression | void>;
175
- setStatus(status: PerspectiveExpression): any;
176
- inbox(filter?: string): Promise<PerspectiveExpression[]>;
177
- addMessageCallback(callback: MessageCallback): any;
178
- }
179
21
  export declare class InteractionParameter {
180
22
  name: string;
181
23
  type: string;
@@ -185,6 +27,12 @@ export declare class InteractionMeta {
185
27
  name: string;
186
28
  parameters: InteractionParameter[];
187
29
  }
30
+ /**
31
+ * Runtime-side interaction object. The runtime constructs one of these
32
+ * from a Language's `interactions(address)` description and exposes
33
+ * `execute()` to UI callers. Language authors describe interactions
34
+ * via the ALDK, not by constructing this type directly.
35
+ */
188
36
  export interface Interaction {
189
37
  readonly label: string;
190
38
  readonly name: string;
@@ -201,44 +49,8 @@ export declare class OnlineAgent {
201
49
  did: DID;
202
50
  status: PerspectiveExpression;
203
51
  }
204
- export type TelepresenceSignalCallback = (payload: PerspectiveExpression, recipientDid?: string) => void;
205
- export interface TelepresenceAdapter {
206
- setOnlineStatus(status: PerspectiveExpression): Promise<void>;
207
- getOnlineAgents(): Promise<OnlineAgent[]>;
208
- sendSignal(remoteAgentDid: string, payload: PerspectiveExpression): Promise<object>;
209
- sendBroadcast(payload: PerspectiveExpression): Promise<object>;
210
- registerSignalCallback(callback: TelepresenceSignalCallback): Promise<void>;
211
- }
212
- /** Interface for Languages that implement queries returning links, i.e. a Perspective (-snapshot)
213
- * Main differentiation between these Languages and LinkLanguages is that this enables
214
- * access to other shared perspectives without forcing a full-sync.
215
- *
216
- * All PerspectiveQuery Languages are supposed to implement `linkQuery` which is a simple graph query
217
- * specifying non or all of source, predicate, target of the links we want to get.
218
- * This is enough to implement simple back-links.
219
- *
220
- * Prolog queries are optional since this requires a Prolog engine to be available.
221
- *
52
+ /**
53
+ * Callback shape used by the client to receive telepresence signals
54
+ * from a Neighbourhood's link Language.
222
55
  */
223
- export interface PerspectiveQueryAdapter {
224
- /** Same semantic as PerspectiveProxy.get(LinkQuery) */
225
- linkQuery(query: LinkQuery): Promise<Perspective>;
226
- /** Tells ADAM if Prolog queries are implemented by this Language.
227
- * If not, prologQuery won't be used, instead in some circumstances,
228
- * linkQuery() might be called with an all-query, followed by using
229
- * ADAM's internal Prolog engine on the result.
230
- */
231
- supportsPrologQueries(): boolean;
232
- /** Same semantic as PerspectiveProxy.infer, will return plain Prolog results */
233
- infer(prologQuery: string): Promise<any>;
234
- /** Specify which links shall be returned through Prolog.
235
- * Assumes unbound variables in query that describe a LinkExpression:
236
- * - Source
237
- * - Predicate
238
- * - Target
239
- * - Author
240
- * - Timestamp
241
- * Will construct a Perspective where each link is a solution to the query.
242
- */
243
- prologQuery(query: string): Promise<Perspective>;
244
- }
56
+ export type TelepresenceSignalCallback = (payload: PerspectiveExpression, recipientDid?: string) => void;
@@ -7,8 +7,33 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
7
7
  var __metadata = (this && this.__metadata) || function (k, v) {
8
8
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
9
9
  };
10
- import { PerspectiveExpression } from '../perspectives/Perspective';
10
+ import { PerspectiveExpression } from "../perspectives/Perspective";
11
11
  import { InputType, Field, ObjectType } from "type-graphql";
12
+ /**
13
+ * # AD4M Language — client-side types
14
+ *
15
+ * This file only contains the client-visible types that the AD4M GraphQL
16
+ * API exposes on top of a running Language — interaction metadata, online
17
+ * agent records, and the telepresence-signal callback shape.
18
+ *
19
+ * **If you're authoring an AD4M Language**, you don't consume types from
20
+ * here — use [`@coasys/ad4m-ldk`](https://www.npmjs.com/package/@coasys/ad4m-ldk)
21
+ * (or the [Rust ALDK](https://crates.io/crates/ad4m-ldk)), which provide
22
+ * the capability traits, typed runtime-import wrappers, and authoring
23
+ * macros/helpers.
24
+ *
25
+ * The normative interface definition lives in
26
+ * [`docs-src/ad4m-lang.wit`](https://github.com/coasys/ad4m/blob/dev/docs-src/ad4m-lang.wit).
27
+ * The prose spec is
28
+ * [`docs-src/language-interface-spec.md`](https://github.com/coasys/ad4m/blob/dev/docs-src/language-interface-spec.md).
29
+ */
30
+ // ----- Interaction metadata --------------------------------------------------
31
+ //
32
+ // Languages optionally publish a list of user-invocable actions per
33
+ // Expression ("interactions"). The runtime surfaces these to UIs via
34
+ // GraphQL, which is why `InteractionParameter` / `InteractionMeta` /
35
+ // `InteractionCall` need the type-graphql decorators — they cross the
36
+ // GraphQL boundary as first-class objects.
12
37
  let InteractionParameter = class InteractionParameter {
13
38
  };
14
39
  __decorate([
@@ -34,7 +59,7 @@ __decorate([
34
59
  __metadata("design:type", String)
35
60
  ], InteractionMeta.prototype, "name", void 0);
36
61
  __decorate([
37
- Field(type => [InteractionParameter]),
62
+ Field(() => [InteractionParameter]),
38
63
  __metadata("design:type", Array)
39
64
  ], InteractionMeta.prototype, "parameters", void 0);
40
65
  InteractionMeta = __decorate([
@@ -63,6 +88,7 @@ InteractionCall = __decorate([
63
88
  __metadata("design:paramtypes", [String, Object])
64
89
  ], InteractionCall);
65
90
  export { InteractionCall };
91
+ // ----- Telepresence ----------------------------------------------------------
66
92
  let OnlineAgent = class OnlineAgent {
67
93
  };
68
94
  __decorate([
@@ -317,7 +317,7 @@ export declare class Ad4mModel {
317
317
  *
318
318
  * @internal
319
319
  */
320
- static instancesFromQueryResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query: Query, result: any[]): Promise<ResultsWithTotalCount<T>>;
320
+ static instancesFromQueryResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query: Query, result: any[], computeTotalCount?: boolean): Promise<ResultsWithTotalCount<T>>;
321
321
  /**
322
322
  * Gets all instances of the model in the perspective that match the query params.
323
323
  *
@@ -477,6 +477,30 @@ export declare class Ad4mModel {
477
477
  save(batchId?: string): Promise<void>;
478
478
  private cleanCopy;
479
479
  private innerUpdate;
480
+ /**
481
+ * Evaluate SPARQL getters for a batch of instances on demand.
482
+ *
483
+ * Use after a shallow collection query (the default) to resolve
484
+ * getter-backed properties for visible items only. This avoids the
485
+ * O(N × getters) cost of evaluating every getter on every instance in
486
+ * a large collection query.
487
+ *
488
+ * @param instances - Array of model instances to evaluate getters on
489
+ * @param perspective - The perspective to query against
490
+ * @param propertyNames - Optional list of getter-backed property names to evaluate.
491
+ * If omitted, all getters are evaluated.
492
+ *
493
+ * @example
494
+ * ```typescript
495
+ * const messages = await Message.findAll(perspective, { parent: channel, limit: 30 });
496
+ * // messages[i].replyingTo is undefined (getter skipped by default)
497
+ *
498
+ * // Evaluate getters for the visible subset
499
+ * await Message.evaluateGetters(messages.slice(0, 10), perspective, ['replyingTo']);
500
+ * // messages[0..9].replyingTo is now populated
501
+ * ```
502
+ */
503
+ static evaluateGetters<T extends Ad4mModel>(instances: T[], perspective: PerspectiveProxy, propertyNames?: string[]): Promise<void>;
480
504
  /**
481
505
  * Gets the model instance with all properties and relations populated.
482
506
  *
@@ -6,7 +6,7 @@ import { getPropertiesMetadata, getRelationsMetadata } from "./decorators";
6
6
  import { resolveParentPredicate } from "./query-common";
7
7
  import { buildParentQuery, buildAuthorAndTimestampQuery, buildPropertiesQuery, buildWhereQuery, buildCountQuery, buildOrderQuery, buildOffsetQuery, buildLimitQuery } from "./query-prolog";
8
8
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
9
- import { buildSPARQLQuery, buildSPARQLGetDataQuery, groupSPARQLResults } from "./query-sparql";
9
+ import { buildSPARQLQuery, buildSPARQLGetDataQuery, groupSPARQLResults, buildSPARQLCountQuery, hasJsOnlyWhereFilters, parseSparqlCount } from "./query-sparql";
10
10
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
11
11
  import { normalizeValue, matchesCondition, hydrateFromLinks, assignValuesToInstance as _assignValuesToInstance, evaluateCustomGettersForInstance, hydrateRelations, } from "./hydration";
12
12
  /**
@@ -681,7 +681,7 @@ export class Ad4mModel {
681
681
  *
682
682
  * @internal
683
683
  */
684
- static async instancesFromQueryResult(perspective, query, result) {
684
+ static async instancesFromQueryResult(perspective, query, result, computeTotalCount = false) {
685
685
  if (!result || result.length === 0)
686
686
  return { results: [], totalCount: 0 };
687
687
  const metadata = this.getModelMetadata();
@@ -746,18 +746,38 @@ export class Ad4mModel {
746
746
  }
747
747
  }));
748
748
  }
749
- // Evaluate custom getters for all instances (single pass)
750
- const getterOpts = requestedProperties.length > 0 || query.include
751
- ? { requestedProperties, include: query.include }
752
- : undefined;
753
- for (const instance of instances) {
754
- await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
749
+ // Evaluate custom getters for all instances.
750
+ // Relation getters (type-conformance filtering) always run — they ensure
751
+ // correctness of @HasMany/@HasOne targets. Property getters only run when
752
+ // deepQuery is true or when where conditions reference getter-backed properties.
753
+ const whereGetterProperties = query.where
754
+ ? Object.keys(query.where).filter((propName) => metadata.properties[propName]?.getter)
755
+ : [];
756
+ const shouldEvaluatePropertyGetters = query.deepQuery === true || whereGetterProperties.length > 0;
757
+ {
758
+ const skipPropertyGetters = !shouldEvaluatePropertyGetters;
759
+ const getterRequestedProperties = shouldEvaluatePropertyGetters
760
+ ? (requestedProperties.length > 0
761
+ ? Array.from(new Set([...requestedProperties, ...whereGetterProperties]))
762
+ : query.deepQuery === true
763
+ ? [] // deepQuery: evaluate all getters
764
+ : whereGetterProperties) // only evaluate where-referenced getters
765
+ : [];
766
+ const getterOpts = {
767
+ ...(getterRequestedProperties.length > 0 && { requestedProperties: getterRequestedProperties }),
768
+ ...(query.include && { include: query.include }),
769
+ skipPropertyGetters,
770
+ };
771
+ for (const instance of instances) {
772
+ await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
773
+ }
755
774
  }
756
775
  // Filter by where conditions that couldn't be filtered in SPARQL
757
776
  // This includes:
758
777
  // - author/timestamp (computed from grouped links)
759
778
  // - Properties with comparison operators (gt, gte, lt, lte, between, contains)
760
- // because fn::parse_literal() comparisons in SPARQL subqueries don't work reliably
779
+ // because <ad4m://fn/parse_literal>() returns strings, making numeric/date
780
+ // comparisons unreliable. Equality, IN, and NOT are pushed to SPARQL.
761
781
  // - Relation-based where clauses (e.g., { post: postId } for @BelongsToOne)
762
782
  // which require reverse-link resolution before filtering
763
783
  let filteredInstances = instances;
@@ -783,9 +803,9 @@ export class Ad4mModel {
783
803
  }
784
804
  continue;
785
805
  }
786
- // Filter ALL property conditions in JS (equality, NOT, IN, comparison operators).
787
- // SPARQL-level filtering with parse_literal is unreliable across environments,
788
- // so we do all property filtering here after hydration resolves values.
806
+ // Filter ALL property conditions in JS (safety net).
807
+ // Equality/IN/NOT are also filtered in SPARQL via <ad4m://fn/parse_literal>()
808
+ // but JS re-validates after hydration resolves values.
789
809
  if (!matchesCondition(instance[propertyName], condition)) {
790
810
  return false;
791
811
  }
@@ -797,7 +817,7 @@ export class Ad4mModel {
797
817
  // If limit/offset is used but no explicit order, default to ordering by timestamp (ASC)
798
818
  // This ensures consistent pagination behavior
799
819
  const effectiveOrder = query.order ||
800
- (query.limit !== undefined || query.offset !== undefined ? { timestamp: 'ASC' } : null);
820
+ (query.limit !== undefined || query.offset !== undefined ? { createdAt: 'ASC' } : null);
801
821
  if (effectiveOrder) {
802
822
  const orderEntries = Object.entries(effectiveOrder);
803
823
  filteredInstances.sort((a, b) => {
@@ -830,11 +850,37 @@ export class Ad4mModel {
830
850
  return 0;
831
851
  });
832
852
  }
833
- // Calculate totalCount BEFORE applying limit/offset
834
- const totalCount = filteredInstances.length;
835
- // Apply offset and limit in JavaScript
853
+ // Determine if SPARQL already applied LIMIT/OFFSET (i.e., the pagination
854
+ // subquery was used). When it was, skip JS-level slicing — instances are
855
+ // already the correct page.
856
+ const allRelsMeta2 = getRelationsMetadata(this);
857
+ const sparqlPaginated = !hasJsOnlyWhereFilters(metadata, allRelsMeta2, query.where)
858
+ && (query.limit !== undefined || query.offset !== undefined)
859
+ && query.order !== undefined && Object.keys(query.order).length > 0;
860
+ // Calculate totalCount BEFORE applying limit/offset.
861
+ // When SPARQL already paginated, filteredInstances.length is the page size,
862
+ // not the total — use a separate COUNT query for the real total.
863
+ // Only run the COUNT query when the caller actually needs it (computeTotalCount=true).
864
+ let totalCount;
865
+ if (sparqlPaginated && computeTotalCount) {
866
+ try {
867
+ const countSparql = buildSPARQLCountQuery(metadata, allRelsMeta2, query, this);
868
+ const countResult = await perspective.querySparql(countSparql);
869
+ totalCount = parseSparqlCount(countResult) ?? filteredInstances.length;
870
+ }
871
+ catch {
872
+ // Fallback: if count query fails, use what we have
873
+ totalCount = filteredInstances.length;
874
+ }
875
+ }
876
+ else {
877
+ totalCount = filteredInstances.length;
878
+ }
879
+ // Apply offset and limit in JavaScript only when SPARQL didn't already paginate.
880
+ // Subscription queries use unpaginated SPARQL, so JS must apply pagination.
881
+ // Direct queries use SPARQL-level pagination, so JS slicing would double-apply.
836
882
  let paginatedInstances = filteredInstances;
837
- if (query.offset !== undefined || query.limit !== undefined) {
883
+ if (!sparqlPaginated && (query.offset !== undefined || query.limit !== undefined)) {
838
884
  const start = query.offset || 0;
839
885
  const end = query.limit ? start + query.limit : undefined;
840
886
  paginatedInstances = filteredInstances.slice(start, end);
@@ -986,7 +1032,7 @@ export class Ad4mModel {
986
1032
  const sparqlQuery = await this.queryToSPARQL(perspective, query);
987
1033
  const rawResult = await perspective.querySparql(sparqlQuery);
988
1034
  const grouped = groupSPARQLResults(rawResult);
989
- return await this.instancesFromQueryResult(perspective, query, grouped);
1035
+ return await this.instancesFromQueryResult(perspective, query, grouped, true);
990
1036
  }
991
1037
  else {
992
1038
  const prologQuery = await this.queryToProlog(perspective, query);
@@ -1024,7 +1070,7 @@ export class Ad4mModel {
1024
1070
  const sparqlQuery = await this.queryToSPARQL(perspective, paginationQuery);
1025
1071
  const rawResult = await perspective.querySparql(sparqlQuery);
1026
1072
  const grouped = groupSPARQLResults(rawResult);
1027
- const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped);
1073
+ const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped, true);
1028
1074
  return { results, totalCount, pageSize, pageNumber };
1029
1075
  }
1030
1076
  else {
@@ -1062,12 +1108,9 @@ export class Ad4mModel {
1062
1108
  * @private
1063
1109
  */
1064
1110
  static async countQueryToSPARQL(perspective, query) {
1065
- // Use the same query as the main query (with GROUP BY), just without LIMIT/OFFSET
1066
- // We'll count the number of rows returned (one row per source)
1067
- const countQuery = { ...query };
1068
- delete countQuery.limit;
1069
- delete countQuery.offset;
1070
- return await this.queryToSPARQL(perspective, countQuery);
1111
+ const metadata = this.getModelMetadata();
1112
+ const allRelMeta = getRelationsMetadata(this);
1113
+ return buildSPARQLCountQuery(metadata, allRelMeta, query, this);
1071
1114
  }
1072
1115
  /**
1073
1116
  * Gets a count of all matching instances.
@@ -1093,11 +1136,22 @@ export class Ad4mModel {
1093
1136
  ? (engine ? 'sparql' : 'prolog')
1094
1137
  : engine;
1095
1138
  if (resolvedEngine === 'sparql') {
1096
- const sparqlQuery = await this.queryToSPARQL(perspective, query);
1097
- const rawResult = await perspective.querySparql(sparqlQuery);
1098
- const grouped = groupSPARQLResults(rawResult);
1099
- const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped);
1100
- return totalCount;
1139
+ // When query has JS-only where filters (gt, between, author, timestamp, etc.),
1140
+ // we must fall back to full hydration + JS filtering to get accurate count.
1141
+ const metadata = this.getModelMetadata();
1142
+ const allRelMeta = getRelationsMetadata(this);
1143
+ if (hasJsOnlyWhereFilters(metadata, allRelMeta, query.where)) {
1144
+ // Fall back to full query + JS filter path for accurate count
1145
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
1146
+ const rawResult = await perspective.querySparql(sparqlQuery);
1147
+ const grouped = groupSPARQLResults(rawResult);
1148
+ const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped, true);
1149
+ return totalCount;
1150
+ }
1151
+ // No JS-only filters — use efficient COUNT query
1152
+ const countSparql = await this.countQueryToSPARQL(perspective, query);
1153
+ const countResult = await perspective.querySparql(countSparql);
1154
+ return parseSparqlCount(countResult) ?? 0;
1101
1155
  }
1102
1156
  else {
1103
1157
  const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
@@ -1385,6 +1439,61 @@ export class Ad4mModel {
1385
1439
  }
1386
1440
  }
1387
1441
  }
1442
+ /**
1443
+ * Evaluate SPARQL getters for a batch of instances on demand.
1444
+ *
1445
+ * Use after a shallow collection query (the default) to resolve
1446
+ * getter-backed properties for visible items only. This avoids the
1447
+ * O(N × getters) cost of evaluating every getter on every instance in
1448
+ * a large collection query.
1449
+ *
1450
+ * @param instances - Array of model instances to evaluate getters on
1451
+ * @param perspective - The perspective to query against
1452
+ * @param propertyNames - Optional list of getter-backed property names to evaluate.
1453
+ * If omitted, all getters are evaluated.
1454
+ *
1455
+ * @example
1456
+ * ```typescript
1457
+ * const messages = await Message.findAll(perspective, { parent: channel, limit: 30 });
1458
+ * // messages[i].replyingTo is undefined (getter skipped by default)
1459
+ *
1460
+ * // Evaluate getters for the visible subset
1461
+ * await Message.evaluateGetters(messages.slice(0, 10), perspective, ['replyingTo']);
1462
+ * // messages[0..9].replyingTo is now populated
1463
+ * ```
1464
+ */
1465
+ static async evaluateGetters(instances, perspective, propertyNames) {
1466
+ if (instances.length === 0)
1467
+ return;
1468
+ const metadata = this.getModelMetadata();
1469
+ const opts = propertyNames && propertyNames.length > 0
1470
+ ? { requestedProperties: propertyNames }
1471
+ : undefined;
1472
+ // Determine which property names will actually be evaluated
1473
+ const evaluatedPropertyNames = [];
1474
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1475
+ if (propMeta.getter) {
1476
+ if (!propertyNames || propertyNames.length === 0 || propertyNames.includes(propName)) {
1477
+ evaluatedPropertyNames.push(propName);
1478
+ }
1479
+ }
1480
+ }
1481
+ for (const instance of instances) {
1482
+ await evaluateCustomGettersForInstance(instance, perspective, metadata, opts);
1483
+ // Sync snapshot so isDirty() doesn't flag getter-only changes.
1484
+ // evaluateGetters() mutates instances in place, but their snapshots
1485
+ // were already taken during hydration. Without this sync, the computed
1486
+ // getter values would make isDirty() return true and save() would try
1487
+ // to write read-only computed properties.
1488
+ const modelInstance = instance;
1489
+ if (modelInstance._snapshot) {
1490
+ for (const propName of evaluatedPropertyNames) {
1491
+ const val = instance[propName];
1492
+ modelInstance._snapshot[propName] = normalizeValue(Array.isArray(val) ? [...val] : val);
1493
+ }
1494
+ }
1495
+ }
1496
+ }
1388
1497
  /**
1389
1498
  * Gets the model instance with all properties and relations populated.
1390
1499
  *