@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.
- package/lib/index.cjs +1060 -147
- package/lib/index.js +1054 -147
- package/lib/src/index.d.ts +0 -1
- package/lib/src/index.js +0 -1
- package/lib/src/language/Language.d.ts +26 -214
- package/lib/src/language/Language.js +28 -2
- package/lib/src/model/Ad4mModel.d.ts +25 -1
- package/lib/src/model/Ad4mModel.js +139 -30
- package/lib/src/model/Ad4mModel.test.js +214 -32
- package/lib/src/model/ModelQueryBuilder.d.ts +19 -0
- package/lib/src/model/ModelQueryBuilder.js +62 -18
- package/lib/src/model/hydration-batching.test.d.ts +7 -0
- package/lib/src/model/hydration-batching.test.js +456 -0
- package/lib/src/model/hydration.d.ts +1 -0
- package/lib/src/model/hydration.js +279 -70
- package/lib/src/model/query-sparql.d.ts +78 -1
- package/lib/src/model/query-sparql.js +447 -16
- package/lib/src/model/query-sparql.test.d.ts +1 -0
- package/lib/src/model/query-sparql.test.js +495 -0
- package/lib/src/model/query-utils.js +4 -0
- package/lib/src/model/subscription-delta.test.d.ts +24 -0
- package/lib/src/model/subscription-delta.test.js +180 -0
- package/lib/src/model/subscription-pool.js +48 -2
- package/lib/src/model/types.d.ts +49 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +2 -0
- package/lib/src/perspectives/PerspectiveClient.js +37 -9
- package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
- package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +3 -0
- package/lib/src/perspectives/PerspectiveProxy.js +15 -0
- package/package.json +1 -1
- package/src/Ad4mClient.test.ts +56 -1
- package/src/index.ts +0 -1
- package/src/language/Language.ts +54 -275
- package/src/model/Ad4mModel.test.ts +222 -35
- package/src/model/Ad4mModel.ts +144 -30
- package/src/model/ModelQueryBuilder.ts +66 -18
- package/src/model/hydration-batching.test.ts +563 -0
- package/src/model/hydration.ts +249 -47
- package/src/model/query-sparql.test.ts +568 -0
- package/src/model/query-sparql.ts +473 -16
- package/src/model/query-utils.ts +4 -0
- package/src/model/subscription-delta.test.ts +207 -0
- package/src/model/subscription-pool.ts +50 -2
- package/src/model/types.ts +50 -1
- package/src/perspectives/PerspectiveClient.test.ts +204 -0
- package/src/perspectives/PerspectiveClient.ts +36 -7
- package/src/perspectives/PerspectiveProxy.ts +18 -0
- package/lib/src/model/query-surreal.d.ts +0 -44
- package/lib/src/model/query-surreal.js +0 -249
- package/lib/src/model/surreal-utils.d.ts +0 -42
- package/lib/src/model/surreal-utils.js +0 -128
- package/src/language/LanguageContext.ts +0 -37
- package/tsconfig-browser.json +0 -82
package/lib/src/index.d.ts
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";
|
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
|
|
2
|
-
import {
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
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
|
-
*
|
|
15
|
-
*
|
|
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
|
|
18
|
-
*
|
|
19
|
-
*
|
|
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
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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
|
|
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
|
|
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(
|
|
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
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
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
|
|
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 (
|
|
787
|
-
//
|
|
788
|
-
//
|
|
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 ? {
|
|
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
|
-
//
|
|
834
|
-
|
|
835
|
-
//
|
|
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
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
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
|
-
|
|
1097
|
-
|
|
1098
|
-
const
|
|
1099
|
-
const
|
|
1100
|
-
|
|
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
|
*
|