@coasys/ad4m 0.13.0-test-1 → 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 +2377 -849
- package/lib/index.js +2354 -846
- package/lib/src/Literal.js +6 -5
- package/lib/src/agent/AgentClient.d.ts +5 -1
- package/lib/src/agent/AgentClient.js +48 -2
- package/lib/src/expression/ExpressionRef.js +2 -2
- package/lib/src/index.d.ts +0 -1
- package/lib/src/index.js +0 -1
- package/lib/src/language/Language.d.ts +26 -176
- package/lib/src/language/Language.js +28 -2
- package/lib/src/model/Ad4mModel.d.ts +52 -28
- package/lib/src/model/Ad4mModel.js +255 -118
- package/lib/src/model/Ad4mModel.test.js +1727 -537
- package/lib/src/model/ModelQueryBuilder.d.ts +67 -34
- package/lib/src/model/ModelQueryBuilder.js +208 -79
- package/lib/src/model/Subject.js +6 -6
- package/lib/src/model/decorators.d.ts +14 -8
- package/lib/src/model/decorators.js +41 -14
- package/lib/src/model/hydration-batch.d.ts +34 -0
- package/lib/src/model/hydration-batch.js +147 -0
- 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 +4 -3
- package/lib/src/model/hydration.js +365 -86
- package/lib/src/model/index.d.ts +4 -1
- package/lib/src/model/index.js +4 -1
- package/lib/src/model/json-schema.js +2 -2
- package/lib/src/model/query-cache.d.ts +30 -0
- package/lib/src/model/query-cache.js +66 -0
- package/lib/src/model/query-cache.test.d.ts +1 -0
- package/lib/src/model/query-cache.test.js +43 -0
- package/lib/src/model/query-common.d.ts +1 -1
- package/lib/src/model/query-common.js +1 -1
- package/lib/src/model/query-sparql-batch.d.ts +17 -0
- package/lib/src/model/query-sparql-batch.js +260 -0
- package/lib/src/model/query-sparql.d.ts +124 -0
- package/lib/src/model/query-sparql.js +767 -0
- 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/{surreal-utils.d.ts → query-utils.d.ts} +12 -9
- package/lib/src/model/{surreal-utils.js → query-utils.js} +43 -27
- package/lib/src/model/relation-filtering.test.js +15 -15
- package/lib/src/model/sdna.js +1 -1
- package/lib/src/model/shacl-gen.js +42 -18
- 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.d.ts +39 -0
- package/lib/src/model/subscription-pool.js +165 -0
- package/lib/src/model/types.d.ts +52 -4
- package/lib/src/model/types.js +1 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +3 -17
- package/lib/src/perspectives/PerspectiveClient.js +42 -66
- 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 +54 -30
- package/lib/src/perspectives/PerspectiveProxy.js +239 -177
- package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveResolver.js +0 -11
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
- package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
- package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
- package/lib/src/runtime/RuntimeResolver.js +56 -0
- package/lib/src/schema.gql +11 -1
- package/lib/src/shacl/SHACLFlow.d.ts +1 -1
- package/lib/src/shacl/SHACLFlow.js +9 -9
- package/lib/src/shacl/SHACLShape.d.ts +1 -1
- package/lib/src/shacl/SHACLShape.js +38 -38
- package/lib/src/typeDefs.js +11 -1
- package/lib/src/utils.d.ts +6 -6
- package/lib/src/utils.js +6 -6
- package/package.json +1 -1
- package/src/Ad4mClient.test.ts +56 -1
- package/src/Literal.test.ts +10 -5
- package/src/Literal.ts +6 -5
- package/src/agent/AgentClient.ts +53 -1
- package/src/expression/ExpressionRef.ts +2 -2
- package/src/index.ts +0 -1
- package/src/language/Language.ts +55 -231
- package/src/model/Ad4mModel.test.ts +1709 -572
- package/src/model/Ad4mModel.ts +274 -120
- package/src/model/ModelQueryBuilder.ts +234 -87
- package/src/model/Subject.ts +6 -6
- package/src/model/decorators.ts +51 -22
- package/src/model/hydration-batch.ts +205 -0
- package/src/model/hydration-batching.test.ts +563 -0
- package/src/model/hydration.ts +349 -84
- package/src/model/index.ts +4 -1
- package/src/model/json-schema.ts +2 -2
- package/src/model/query-cache.test.ts +54 -0
- package/src/model/query-cache.ts +79 -0
- package/src/model/query-common.ts +1 -1
- package/src/model/query-sparql-batch.ts +301 -0
- package/src/model/query-sparql.test.ts +568 -0
- package/src/model/query-sparql.ts +820 -0
- package/src/model/{surreal-utils.ts → query-utils.ts} +44 -27
- package/src/model/relation-filtering.test.ts +15 -15
- package/src/model/sdna.ts +1 -1
- package/src/model/shacl-gen.ts +42 -17
- package/src/model/subscription-delta.test.ts +207 -0
- package/src/model/subscription-pool.ts +211 -0
- package/src/model/types.ts +53 -4
- package/src/perspectives/PerspectiveClient.test.ts +204 -0
- package/src/perspectives/PerspectiveClient.ts +41 -68
- package/src/perspectives/PerspectiveProxy.ts +244 -181
- package/src/perspectives/PerspectiveResolver.ts +0 -8
- package/src/perspectives/WakerSubscriptionManager.ts +8 -9
- package/src/runtime/RuntimeResolver.ts +43 -0
- package/src/shacl/SHACLFlow.ts +9 -9
- package/src/shacl/SHACLShape.ts +39 -39
- package/src/utils.ts +6 -6
- package/lib/src/model/query-surreal.d.ts +0 -44
- package/lib/src/model/query-surreal.js +0 -249
- package/src/language/LanguageContext.ts +0 -37
- package/src/model/query-surreal.ts +0 -280
- package/tsconfig-browser.json +0 -82
|
@@ -33,7 +33,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
33
33
|
private modelClassName;
|
|
34
34
|
private ctor;
|
|
35
35
|
private currentSubscription?;
|
|
36
|
-
private
|
|
36
|
+
private engineFlag;
|
|
37
37
|
constructor(perspective: PerspectiveProxy, ctor: typeof Ad4mModel, query?: Query);
|
|
38
38
|
/**
|
|
39
39
|
* Disposes of the current subscription if one exists.
|
|
@@ -158,6 +158,25 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
158
158
|
* ```
|
|
159
159
|
*/
|
|
160
160
|
properties(properties: string[]): ModelQueryBuilder<T>;
|
|
161
|
+
/**
|
|
162
|
+
* Opts in to evaluating SPARQL property getters during collection hydration.
|
|
163
|
+
*
|
|
164
|
+
* By default, collection queries skip getter evaluation for performance.
|
|
165
|
+
* Call `.deepQuery()` when you need getter-backed properties in the result set.
|
|
166
|
+
*
|
|
167
|
+
* @returns The query builder for chaining
|
|
168
|
+
*
|
|
169
|
+
* @example
|
|
170
|
+
* ```typescript
|
|
171
|
+
* const messages = await Message.query(perspective)
|
|
172
|
+
* .parent(channel)
|
|
173
|
+
* .deepQuery()
|
|
174
|
+
* .limit(30)
|
|
175
|
+
* .get();
|
|
176
|
+
* // messages[i].replyingTo is populated
|
|
177
|
+
* ```
|
|
178
|
+
*/
|
|
179
|
+
deepQuery(): ModelQueryBuilder<T>;
|
|
161
180
|
/**
|
|
162
181
|
* Specifies which relations to eager-load (hydrate into model instances).
|
|
163
182
|
*
|
|
@@ -187,31 +206,9 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
187
206
|
include(map: IncludeMap): ModelQueryBuilder<T>;
|
|
188
207
|
overrideModelClassName(className: string): ModelQueryBuilder<T>;
|
|
189
208
|
/**
|
|
190
|
-
*
|
|
191
|
-
*
|
|
192
|
-
* @param enabled - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
|
|
193
|
-
* @returns The query builder for chaining
|
|
194
|
-
*
|
|
195
|
-
* @example
|
|
196
|
-
* ```typescript
|
|
197
|
-
* // Use SurrealDB (default)
|
|
198
|
-
* const recipes = await Recipe.query(perspective)
|
|
199
|
-
* .where({ category: "Dessert" })
|
|
200
|
-
* .useSurrealDB(true)
|
|
201
|
-
* .get();
|
|
202
|
-
*
|
|
203
|
-
* // Use Prolog (legacy)
|
|
204
|
-
* const recipesProlog = await Recipe.query(perspective)
|
|
205
|
-
* .where({ category: "Dessert" })
|
|
206
|
-
* .useSurrealDB(false)
|
|
207
|
-
* .get();
|
|
208
|
-
* ```
|
|
209
|
-
*
|
|
210
|
-
* @remarks
|
|
211
|
-
* Note: Subscriptions (subscribe(), countSubscribe(), paginateSubscribe()) default to SurrealDB live queries
|
|
212
|
-
* if useSurrealDB(true) is set (default).
|
|
209
|
+
* Sets the query engine to use.
|
|
213
210
|
*/
|
|
214
|
-
|
|
211
|
+
engine(eng: 'sparql' | 'prolog'): ModelQueryBuilder<T>;
|
|
215
212
|
/**
|
|
216
213
|
* Executes the query once and returns the results.
|
|
217
214
|
*
|
|
@@ -225,6 +222,19 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
225
222
|
* ```
|
|
226
223
|
*/
|
|
227
224
|
get(): Promise<T[]>;
|
|
225
|
+
/**
|
|
226
|
+
* Executes the query once using SPARQL and returns the results.
|
|
227
|
+
*/
|
|
228
|
+
getSparql(): Promise<T[]>;
|
|
229
|
+
/**
|
|
230
|
+
* Shared SPARQL query execution logic used by both get() and getSparql().
|
|
231
|
+
*/
|
|
232
|
+
private executeSparqlQuery;
|
|
233
|
+
/**
|
|
234
|
+
* Groups raw SPARQL results and hydrates them into model instances.
|
|
235
|
+
* Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
|
|
236
|
+
*/
|
|
237
|
+
private processSparqlResult;
|
|
228
238
|
/**
|
|
229
239
|
* Returns the first matching instance, or `null` if none match.
|
|
230
240
|
*
|
|
@@ -244,7 +254,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
244
254
|
* Subscribes to the query and receives updates when results change.
|
|
245
255
|
*
|
|
246
256
|
* This method:
|
|
247
|
-
* 1. Creates and initializes a
|
|
257
|
+
* 1. Creates and initializes a SPARQL live query subscription (default)
|
|
248
258
|
* 2. Sets up the callback to process future updates
|
|
249
259
|
* 3. Returns the initial results immediately
|
|
250
260
|
*
|
|
@@ -268,10 +278,14 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
268
278
|
* ```
|
|
269
279
|
*
|
|
270
280
|
* @remarks
|
|
271
|
-
* By default, this uses
|
|
272
|
-
* Prolog subscriptions remain available via `.
|
|
281
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
282
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
273
283
|
*/
|
|
274
284
|
subscribe(callback: (results: T[]) => void): Promise<T[]>;
|
|
285
|
+
/**
|
|
286
|
+
* Subscribes to the query and receives updates using SPARQL.
|
|
287
|
+
*/
|
|
288
|
+
subscribeSparql(callback: (results: T[]) => void): Promise<T[]>;
|
|
275
289
|
/**
|
|
276
290
|
* Gets the total count of matching entities.
|
|
277
291
|
*
|
|
@@ -285,11 +299,16 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
285
299
|
* ```
|
|
286
300
|
*/
|
|
287
301
|
count(): Promise<number>;
|
|
302
|
+
/**
|
|
303
|
+
* Gets the total count of matching entities using SPARQL.
|
|
304
|
+
* Delegates to count() with SPARQL engine forced.
|
|
305
|
+
*/
|
|
306
|
+
countSparql(): Promise<number>;
|
|
288
307
|
/**
|
|
289
308
|
* Subscribes to count updates for matching entities.
|
|
290
309
|
*
|
|
291
310
|
* This method:
|
|
292
|
-
* 1. Creates and initializes a
|
|
311
|
+
* 1. Creates and initializes a SPARQL live query subscription for the count (default)
|
|
293
312
|
* 2. Sets up the callback to process future count updates
|
|
294
313
|
* 3. Returns the initial count immediately
|
|
295
314
|
*
|
|
@@ -313,10 +332,14 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
313
332
|
* ```
|
|
314
333
|
*
|
|
315
334
|
* @remarks
|
|
316
|
-
* By default, this uses
|
|
317
|
-
* Prolog subscriptions remain available via `.
|
|
335
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
336
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
318
337
|
*/
|
|
319
338
|
countSubscribe(callback: (count: number) => void): Promise<number>;
|
|
339
|
+
/**
|
|
340
|
+
* Subscribes to count updates using SPARQL.
|
|
341
|
+
*/
|
|
342
|
+
countSubscribeSparql(callback: (count: number) => void): Promise<number>;
|
|
320
343
|
/**
|
|
321
344
|
* Gets a page of results with pagination metadata.
|
|
322
345
|
*
|
|
@@ -333,11 +356,16 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
333
356
|
* ```
|
|
334
357
|
*/
|
|
335
358
|
paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
|
|
359
|
+
/**
|
|
360
|
+
* Gets a page of results using SPARQL.
|
|
361
|
+
* Delegates to paginate() with SPARQL engine forced.
|
|
362
|
+
*/
|
|
363
|
+
paginateSparql(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
|
|
336
364
|
/**
|
|
337
365
|
* Subscribes to paginated results updates.
|
|
338
366
|
*
|
|
339
367
|
* This method:
|
|
340
|
-
* 1. Creates and initializes a
|
|
368
|
+
* 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
|
|
341
369
|
* 2. Sets up the callback to process future page updates
|
|
342
370
|
* 3. Returns the initial page immediately
|
|
343
371
|
*
|
|
@@ -363,8 +391,13 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
363
391
|
* ```
|
|
364
392
|
*
|
|
365
393
|
* @remarks
|
|
366
|
-
* By default, this uses
|
|
367
|
-
* Prolog subscriptions remain available via `.
|
|
394
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
395
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
368
396
|
*/
|
|
369
397
|
paginateSubscribe(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
|
|
398
|
+
/**
|
|
399
|
+
* Subscribes to paginated results updates using SPARQL.
|
|
400
|
+
* Delegates to paginateSubscribe() with SPARQL engine forced.
|
|
401
|
+
*/
|
|
402
|
+
paginateSubscribeSparql(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
|
|
370
403
|
}
|
|
@@ -4,6 +4,9 @@
|
|
|
4
4
|
* Allows building queries with a chainable interface and either
|
|
5
5
|
* running them once or subscribing to real-time updates.
|
|
6
6
|
*/
|
|
7
|
+
import { groupSPARQLResults, hasJsOnlyWhereFilters, parseSparqlCount } from "./query-sparql";
|
|
8
|
+
import { getRelationsMetadata } from "./decorators";
|
|
9
|
+
import { pooledSubscribe } from "./subscription-pool";
|
|
7
10
|
/** Query builder for Ad4mModel queries.
|
|
8
11
|
* Allows building queries with a fluent interface and either running them once
|
|
9
12
|
* or subscribing to updates.
|
|
@@ -28,7 +31,7 @@ export class ModelQueryBuilder {
|
|
|
28
31
|
constructor(perspective, ctor, query) {
|
|
29
32
|
this.queryParams = {};
|
|
30
33
|
this.modelClassName = null;
|
|
31
|
-
this.
|
|
34
|
+
this.engineFlag = 'sparql';
|
|
32
35
|
this.perspective = perspective;
|
|
33
36
|
this.ctor = ctor;
|
|
34
37
|
if (query)
|
|
@@ -201,6 +204,28 @@ export class ModelQueryBuilder {
|
|
|
201
204
|
this.queryParams.properties = properties;
|
|
202
205
|
return this;
|
|
203
206
|
}
|
|
207
|
+
/**
|
|
208
|
+
* Opts in to evaluating SPARQL property getters during collection hydration.
|
|
209
|
+
*
|
|
210
|
+
* By default, collection queries skip getter evaluation for performance.
|
|
211
|
+
* Call `.deepQuery()` when you need getter-backed properties in the result set.
|
|
212
|
+
*
|
|
213
|
+
* @returns The query builder for chaining
|
|
214
|
+
*
|
|
215
|
+
* @example
|
|
216
|
+
* ```typescript
|
|
217
|
+
* const messages = await Message.query(perspective)
|
|
218
|
+
* .parent(channel)
|
|
219
|
+
* .deepQuery()
|
|
220
|
+
* .limit(30)
|
|
221
|
+
* .get();
|
|
222
|
+
* // messages[i].replyingTo is populated
|
|
223
|
+
* ```
|
|
224
|
+
*/
|
|
225
|
+
deepQuery() {
|
|
226
|
+
this.queryParams.deepQuery = true;
|
|
227
|
+
return this;
|
|
228
|
+
}
|
|
204
229
|
/**
|
|
205
230
|
* Specifies which relations to eager-load (hydrate into model instances).
|
|
206
231
|
*
|
|
@@ -236,32 +261,10 @@ export class ModelQueryBuilder {
|
|
|
236
261
|
return this;
|
|
237
262
|
}
|
|
238
263
|
/**
|
|
239
|
-
*
|
|
240
|
-
*
|
|
241
|
-
* @param enabled - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
|
|
242
|
-
* @returns The query builder for chaining
|
|
243
|
-
*
|
|
244
|
-
* @example
|
|
245
|
-
* ```typescript
|
|
246
|
-
* // Use SurrealDB (default)
|
|
247
|
-
* const recipes = await Recipe.query(perspective)
|
|
248
|
-
* .where({ category: "Dessert" })
|
|
249
|
-
* .useSurrealDB(true)
|
|
250
|
-
* .get();
|
|
251
|
-
*
|
|
252
|
-
* // Use Prolog (legacy)
|
|
253
|
-
* const recipesProlog = await Recipe.query(perspective)
|
|
254
|
-
* .where({ category: "Dessert" })
|
|
255
|
-
* .useSurrealDB(false)
|
|
256
|
-
* .get();
|
|
257
|
-
* ```
|
|
258
|
-
*
|
|
259
|
-
* @remarks
|
|
260
|
-
* Note: Subscriptions (subscribe(), countSubscribe(), paginateSubscribe()) default to SurrealDB live queries
|
|
261
|
-
* if useSurrealDB(true) is set (default).
|
|
264
|
+
* Sets the query engine to use.
|
|
262
265
|
*/
|
|
263
|
-
|
|
264
|
-
this.
|
|
266
|
+
engine(eng) {
|
|
267
|
+
this.engineFlag = eng;
|
|
265
268
|
return this;
|
|
266
269
|
}
|
|
267
270
|
/**
|
|
@@ -278,10 +281,8 @@ export class ModelQueryBuilder {
|
|
|
278
281
|
*/
|
|
279
282
|
async get() {
|
|
280
283
|
let results;
|
|
281
|
-
if (this.
|
|
282
|
-
|
|
283
|
-
const result = await this.perspective.querySurrealDB(surrealQuery);
|
|
284
|
-
({ results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result));
|
|
284
|
+
if (this.engineFlag === 'sparql') {
|
|
285
|
+
results = await this.executeSparqlQuery();
|
|
285
286
|
}
|
|
286
287
|
else {
|
|
287
288
|
const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
@@ -290,6 +291,29 @@ export class ModelQueryBuilder {
|
|
|
290
291
|
}
|
|
291
292
|
return results;
|
|
292
293
|
}
|
|
294
|
+
/**
|
|
295
|
+
* Executes the query once using SPARQL and returns the results.
|
|
296
|
+
*/
|
|
297
|
+
async getSparql() {
|
|
298
|
+
return this.executeSparqlQuery();
|
|
299
|
+
}
|
|
300
|
+
/**
|
|
301
|
+
* Shared SPARQL query execution logic used by both get() and getSparql().
|
|
302
|
+
*/
|
|
303
|
+
async executeSparqlQuery() {
|
|
304
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
305
|
+
const rawResult = await this.perspective.querySparql(sparqlQuery);
|
|
306
|
+
const { results } = await this.processSparqlResult(rawResult);
|
|
307
|
+
return results;
|
|
308
|
+
}
|
|
309
|
+
/**
|
|
310
|
+
* Groups raw SPARQL results and hydrates them into model instances.
|
|
311
|
+
* Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
|
|
312
|
+
*/
|
|
313
|
+
async processSparqlResult(rawResult, queryOverride, computeTotalCount = false) {
|
|
314
|
+
const grouped = groupSPARQLResults(Array.isArray(rawResult) ? rawResult : []);
|
|
315
|
+
return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped, computeTotalCount);
|
|
316
|
+
}
|
|
293
317
|
/**
|
|
294
318
|
* Returns the first matching instance, or `null` if none match.
|
|
295
319
|
*
|
|
@@ -313,7 +337,7 @@ export class ModelQueryBuilder {
|
|
|
313
337
|
* Subscribes to the query and receives updates when results change.
|
|
314
338
|
*
|
|
315
339
|
* This method:
|
|
316
|
-
* 1. Creates and initializes a
|
|
340
|
+
* 1. Creates and initializes a SPARQL live query subscription (default)
|
|
317
341
|
* 2. Sets up the callback to process future updates
|
|
318
342
|
* 3. Returns the initial results immediately
|
|
319
343
|
*
|
|
@@ -337,26 +361,40 @@ export class ModelQueryBuilder {
|
|
|
337
361
|
* ```
|
|
338
362
|
*
|
|
339
363
|
* @remarks
|
|
340
|
-
* By default, this uses
|
|
341
|
-
* Prolog subscriptions remain available via `.
|
|
364
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
365
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
342
366
|
*/
|
|
343
367
|
async subscribe(callback) {
|
|
344
368
|
// Clean up any existing subscription
|
|
345
369
|
this.dispose();
|
|
346
370
|
const ctor = this.ctor;
|
|
347
|
-
if (this.
|
|
348
|
-
const
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
371
|
+
if (this.engineFlag === 'sparql') {
|
|
372
|
+
const sparqlQuery = await ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
373
|
+
// Track last emitted result fingerprint to suppress duplicate callbacks
|
|
374
|
+
let lastResultFingerprint = null;
|
|
375
|
+
const buildFingerprint = (results) => {
|
|
376
|
+
if (results.length === 0)
|
|
377
|
+
return '0:';
|
|
378
|
+
// Must include relation data (e.g. tags) — not just id/timestamp.
|
|
379
|
+
// Otherwise @HasMany changes on existing instances are suppressed as duplicates.
|
|
380
|
+
return JSON.stringify(results, (_, v) => typeof v === 'function' ? undefined : v);
|
|
353
381
|
};
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
382
|
+
const hydrate = async (rawResult) => {
|
|
383
|
+
const { results } = await this.processSparqlResult(rawResult);
|
|
384
|
+
return results;
|
|
385
|
+
};
|
|
386
|
+
const pooled = await pooledSubscribe(this.perspective, sparqlQuery, hydrate, (hydratedResults) => {
|
|
387
|
+
const fp = buildFingerprint(hydratedResults);
|
|
388
|
+
if (fp === lastResultFingerprint)
|
|
389
|
+
return;
|
|
390
|
+
lastResultFingerprint = fp;
|
|
391
|
+
callback(hydratedResults);
|
|
392
|
+
});
|
|
393
|
+
// Store dispose function as subscription
|
|
394
|
+
this.currentSubscription = { dispose: pooled.dispose };
|
|
395
|
+
const initialResults = pooled.initialResult;
|
|
396
|
+
lastResultFingerprint = buildFingerprint(initialResults);
|
|
397
|
+
return initialResults;
|
|
360
398
|
}
|
|
361
399
|
else {
|
|
362
400
|
const query = await ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
@@ -367,11 +405,26 @@ export class ModelQueryBuilder {
|
|
|
367
405
|
};
|
|
368
406
|
this.currentSubscription.onResult(processResults);
|
|
369
407
|
const { results } = await ctor.instancesFromPrologResult(this.perspective, this.queryParams, this.currentSubscription.result);
|
|
370
|
-
//
|
|
371
|
-
callback(results);
|
|
408
|
+
// Initial results returned via Promise only — callback is for subsequent updates
|
|
372
409
|
return results;
|
|
373
410
|
}
|
|
374
411
|
}
|
|
412
|
+
/**
|
|
413
|
+
* Subscribes to the query and receives updates using SPARQL.
|
|
414
|
+
*/
|
|
415
|
+
async subscribeSparql(callback) {
|
|
416
|
+
this.dispose();
|
|
417
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
418
|
+
this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
|
|
419
|
+
const processResults = async (result) => {
|
|
420
|
+
const { results } = await this.processSparqlResult(result);
|
|
421
|
+
callback(results);
|
|
422
|
+
};
|
|
423
|
+
this.currentSubscription.onResult(processResults);
|
|
424
|
+
const { results } = await this.processSparqlResult(this.currentSubscription.result);
|
|
425
|
+
// Initial results returned via Promise only — callback is for subsequent updates
|
|
426
|
+
return results;
|
|
427
|
+
}
|
|
375
428
|
/**
|
|
376
429
|
* Gets the total count of matching entities.
|
|
377
430
|
*
|
|
@@ -385,14 +438,20 @@ export class ModelQueryBuilder {
|
|
|
385
438
|
* ```
|
|
386
439
|
*/
|
|
387
440
|
async count() {
|
|
388
|
-
if (this.
|
|
389
|
-
|
|
390
|
-
const
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
441
|
+
if (this.engineFlag === 'sparql') {
|
|
442
|
+
// When query has JS-only where filters, fall back to full hydration
|
|
443
|
+
const metadata = this.ctor.getModelMetadata();
|
|
444
|
+
const allRelMeta = getRelationsMetadata(this.ctor);
|
|
445
|
+
if (hasJsOnlyWhereFilters(metadata, allRelMeta, this.queryParams.where)) {
|
|
446
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
447
|
+
const rawResult = await this.perspective.querySparql(sparqlQuery);
|
|
448
|
+
const { totalCount } = await this.processSparqlResult(rawResult, undefined, true);
|
|
449
|
+
return totalCount;
|
|
450
|
+
}
|
|
451
|
+
// Use efficient COUNT query — no hydration
|
|
452
|
+
const countSparql = await this.ctor.countQueryToSPARQL(this.perspective, this.queryParams);
|
|
453
|
+
const countResult = await this.perspective.querySparql(countSparql);
|
|
454
|
+
return parseSparqlCount(countResult) ?? 0;
|
|
396
455
|
}
|
|
397
456
|
else {
|
|
398
457
|
const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
@@ -400,11 +459,25 @@ export class ModelQueryBuilder {
|
|
|
400
459
|
return result?.[0]?.TotalCount || 0;
|
|
401
460
|
}
|
|
402
461
|
}
|
|
462
|
+
/**
|
|
463
|
+
* Gets the total count of matching entities using SPARQL.
|
|
464
|
+
* Delegates to count() with SPARQL engine forced.
|
|
465
|
+
*/
|
|
466
|
+
async countSparql() {
|
|
467
|
+
const prev = this.engineFlag;
|
|
468
|
+
this.engineFlag = 'sparql';
|
|
469
|
+
try {
|
|
470
|
+
return await this.count();
|
|
471
|
+
}
|
|
472
|
+
finally {
|
|
473
|
+
this.engineFlag = prev;
|
|
474
|
+
}
|
|
475
|
+
}
|
|
403
476
|
/**
|
|
404
477
|
* Subscribes to count updates for matching entities.
|
|
405
478
|
*
|
|
406
479
|
* This method:
|
|
407
|
-
* 1. Creates and initializes a
|
|
480
|
+
* 1. Creates and initializes a SPARQL live query subscription for the count (default)
|
|
408
481
|
* 2. Sets up the callback to process future count updates
|
|
409
482
|
* 3. Returns the initial count immediately
|
|
410
483
|
*
|
|
@@ -428,22 +501,22 @@ export class ModelQueryBuilder {
|
|
|
428
501
|
* ```
|
|
429
502
|
*
|
|
430
503
|
* @remarks
|
|
431
|
-
* By default, this uses
|
|
432
|
-
* Prolog subscriptions remain available via `.
|
|
504
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
505
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
433
506
|
*/
|
|
434
507
|
async countSubscribe(callback) {
|
|
435
508
|
// Clean up any existing subscription
|
|
436
509
|
this.dispose();
|
|
437
|
-
if (this.
|
|
438
|
-
const
|
|
439
|
-
this.currentSubscription = await this.perspective.
|
|
510
|
+
if (this.engineFlag === 'sparql') {
|
|
511
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
512
|
+
this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
|
|
440
513
|
const processResults = async (result) => {
|
|
441
|
-
const { totalCount } = await this.
|
|
514
|
+
const { totalCount } = await this.processSparqlResult(result, undefined, true);
|
|
442
515
|
callback(totalCount);
|
|
443
516
|
};
|
|
444
517
|
this.currentSubscription.onResult(processResults);
|
|
445
|
-
const { totalCount } = await this.
|
|
446
|
-
callback
|
|
518
|
+
const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
|
|
519
|
+
// Initial count returned via Promise — callback for updates only
|
|
447
520
|
return totalCount;
|
|
448
521
|
}
|
|
449
522
|
else {
|
|
@@ -455,10 +528,26 @@ export class ModelQueryBuilder {
|
|
|
455
528
|
};
|
|
456
529
|
this.currentSubscription.onResult(processResults);
|
|
457
530
|
const initialCount = this.currentSubscription.result?.[0]?.TotalCount || 0;
|
|
458
|
-
callback
|
|
531
|
+
// Initial count returned via Promise — callback for subsequent updates only
|
|
459
532
|
return initialCount;
|
|
460
533
|
}
|
|
461
534
|
}
|
|
535
|
+
/**
|
|
536
|
+
* Subscribes to count updates using SPARQL.
|
|
537
|
+
*/
|
|
538
|
+
async countSubscribeSparql(callback) {
|
|
539
|
+
this.dispose();
|
|
540
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
541
|
+
this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
|
|
542
|
+
const processResults = async (result) => {
|
|
543
|
+
const { totalCount } = await this.processSparqlResult(result, undefined, true);
|
|
544
|
+
callback(totalCount);
|
|
545
|
+
};
|
|
546
|
+
this.currentSubscription.onResult(processResults);
|
|
547
|
+
const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
|
|
548
|
+
// Initial count returned via Promise — callback for updates only
|
|
549
|
+
return totalCount;
|
|
550
|
+
}
|
|
462
551
|
/**
|
|
463
552
|
* Gets a page of results with pagination metadata.
|
|
464
553
|
*
|
|
@@ -476,10 +565,10 @@ export class ModelQueryBuilder {
|
|
|
476
565
|
*/
|
|
477
566
|
async paginate(pageSize, pageNumber) {
|
|
478
567
|
const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
|
|
479
|
-
if (this.
|
|
480
|
-
const
|
|
481
|
-
const result = await this.perspective.
|
|
482
|
-
const { results, totalCount } =
|
|
568
|
+
if (this.engineFlag === 'sparql') {
|
|
569
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
|
|
570
|
+
const result = await this.perspective.querySparql(sparqlQuery);
|
|
571
|
+
const { results, totalCount } = await this.processSparqlResult(result, paginationQuery, true);
|
|
483
572
|
return { results, totalCount, pageSize, pageNumber };
|
|
484
573
|
}
|
|
485
574
|
else {
|
|
@@ -489,11 +578,25 @@ export class ModelQueryBuilder {
|
|
|
489
578
|
return { results, totalCount, pageSize, pageNumber };
|
|
490
579
|
}
|
|
491
580
|
}
|
|
581
|
+
/**
|
|
582
|
+
* Gets a page of results using SPARQL.
|
|
583
|
+
* Delegates to paginate() with SPARQL engine forced.
|
|
584
|
+
*/
|
|
585
|
+
async paginateSparql(pageSize, pageNumber) {
|
|
586
|
+
const prev = this.engineFlag;
|
|
587
|
+
this.engineFlag = 'sparql';
|
|
588
|
+
try {
|
|
589
|
+
return await this.paginate(pageSize, pageNumber);
|
|
590
|
+
}
|
|
591
|
+
finally {
|
|
592
|
+
this.engineFlag = prev;
|
|
593
|
+
}
|
|
594
|
+
}
|
|
492
595
|
/**
|
|
493
596
|
* Subscribes to paginated results updates.
|
|
494
597
|
*
|
|
495
598
|
* This method:
|
|
496
|
-
* 1. Creates and initializes a
|
|
599
|
+
* 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
|
|
497
600
|
* 2. Sets up the callback to process future page updates
|
|
498
601
|
* 3. Returns the initial page immediately
|
|
499
602
|
*
|
|
@@ -519,24 +622,36 @@ export class ModelQueryBuilder {
|
|
|
519
622
|
* ```
|
|
520
623
|
*
|
|
521
624
|
* @remarks
|
|
522
|
-
* By default, this uses
|
|
523
|
-
* Prolog subscriptions remain available via `.
|
|
625
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
626
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
524
627
|
*/
|
|
525
628
|
async paginateSubscribe(pageSize, pageNumber, callback) {
|
|
526
629
|
// Clean up any existing subscription
|
|
527
630
|
this.dispose();
|
|
528
631
|
const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
|
|
529
|
-
if (this.
|
|
530
|
-
|
|
531
|
-
|
|
632
|
+
if (this.engineFlag === 'sparql') {
|
|
633
|
+
// Subscribe to the FULL result set (no LIMIT/OFFSET) so the subscription
|
|
634
|
+
// detects changes anywhere in the dataset (e.g. new items beyond current page).
|
|
635
|
+
// Pagination is applied in JS when processing each update.
|
|
636
|
+
const subscriptionParams = { ...(this.queryParams || {}) };
|
|
637
|
+
delete subscriptionParams.limit;
|
|
638
|
+
delete subscriptionParams.offset;
|
|
639
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, subscriptionParams);
|
|
640
|
+
this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
|
|
641
|
+
// Query for processSparqlResult has NO limit/offset — gets all results, totalCount via count:true
|
|
642
|
+
const fullQuery = { ...(this.queryParams || {}), count: true };
|
|
532
643
|
const processResults = async (result) => {
|
|
533
|
-
const { results, totalCount } =
|
|
644
|
+
const { results: allResults, totalCount } = await this.processSparqlResult(result, fullQuery, true);
|
|
645
|
+
const start = pageSize * (pageNumber - 1);
|
|
646
|
+
const results = allResults.slice(start, start + pageSize);
|
|
534
647
|
callback({ results, totalCount, pageSize, pageNumber });
|
|
535
648
|
};
|
|
536
649
|
this.currentSubscription.onResult(processResults);
|
|
537
|
-
const { results, totalCount } =
|
|
650
|
+
const { results: allResults, totalCount } = await this.processSparqlResult(this.currentSubscription.result, fullQuery, true);
|
|
651
|
+
const start = pageSize * (pageNumber - 1);
|
|
652
|
+
const results = allResults.slice(start, start + pageSize);
|
|
538
653
|
const initialPage = { results, totalCount, pageSize, pageNumber };
|
|
539
|
-
callback
|
|
654
|
+
// Initial page returned via Promise — callback for subsequent updates only
|
|
540
655
|
return initialPage;
|
|
541
656
|
}
|
|
542
657
|
else {
|
|
@@ -549,8 +664,22 @@ export class ModelQueryBuilder {
|
|
|
549
664
|
this.currentSubscription.onResult(processResults);
|
|
550
665
|
const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result));
|
|
551
666
|
const initialPrologPage = { results, totalCount, pageSize, pageNumber };
|
|
552
|
-
callback
|
|
667
|
+
// Initial page returned via Promise — callback for subsequent updates only
|
|
553
668
|
return initialPrologPage;
|
|
554
669
|
}
|
|
555
670
|
}
|
|
671
|
+
/**
|
|
672
|
+
* Subscribes to paginated results updates using SPARQL.
|
|
673
|
+
* Delegates to paginateSubscribe() with SPARQL engine forced.
|
|
674
|
+
*/
|
|
675
|
+
async paginateSubscribeSparql(pageSize, pageNumber, callback) {
|
|
676
|
+
const prev = this.engineFlag;
|
|
677
|
+
this.engineFlag = 'sparql';
|
|
678
|
+
try {
|
|
679
|
+
return await this.paginateSubscribe(pageSize, pageNumber, callback);
|
|
680
|
+
}
|
|
681
|
+
finally {
|
|
682
|
+
this.engineFlag = prev;
|
|
683
|
+
}
|
|
684
|
+
}
|
|
556
685
|
}
|
package/lib/src/model/Subject.js
CHANGED
|
@@ -55,12 +55,12 @@ export class Subject {
|
|
|
55
55
|
Object.defineProperty(this, p, {
|
|
56
56
|
configurable: true,
|
|
57
57
|
get: async () => {
|
|
58
|
-
// Use
|
|
58
|
+
// Use SPARQL for data queries
|
|
59
59
|
try {
|
|
60
|
-
return await __classPrivateFieldGet(this, _Subject_perspective, "f").
|
|
60
|
+
return await __classPrivateFieldGet(this, _Subject_perspective, "f").getPropertyValueViaSparql(__classPrivateFieldGet(this, _Subject_baseExpression, "f"), __classPrivateFieldGet(this, _Subject_subjectClassName, "f"), p);
|
|
61
61
|
}
|
|
62
62
|
catch (err) {
|
|
63
|
-
console.warn(`Failed to get property ${p} via
|
|
63
|
+
console.warn(`Failed to get property ${p} via SPARQL:`, err);
|
|
64
64
|
return undefined;
|
|
65
65
|
}
|
|
66
66
|
}
|
|
@@ -94,12 +94,12 @@ export class Subject {
|
|
|
94
94
|
Object.defineProperty(this, c, {
|
|
95
95
|
configurable: true,
|
|
96
96
|
get: async () => {
|
|
97
|
-
// Use
|
|
97
|
+
// Use SPARQL for data queries
|
|
98
98
|
try {
|
|
99
|
-
return await __classPrivateFieldGet(this, _Subject_perspective, "f").
|
|
99
|
+
return await __classPrivateFieldGet(this, _Subject_perspective, "f").getRelationValuesViaSparql(__classPrivateFieldGet(this, _Subject_baseExpression, "f"), __classPrivateFieldGet(this, _Subject_subjectClassName, "f"), c);
|
|
100
100
|
}
|
|
101
101
|
catch (err) {
|
|
102
|
-
console.warn(`Failed to get relation ${c} via
|
|
102
|
+
console.warn(`Failed to get relation ${c} via SPARQL:`, err);
|
|
103
103
|
return [];
|
|
104
104
|
}
|
|
105
105
|
}
|