@coasys/ad4m 0.13.0-test-1 → 0.13.0-test-2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/index.cjs +1392 -777
- package/lib/index.js +1376 -775
- 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/language/Language.d.ts +41 -3
- package/lib/src/model/Ad4mModel.d.ts +28 -28
- package/lib/src/model/Ad4mModel.js +129 -101
- package/lib/src/model/Ad4mModel.test.js +1543 -535
- package/lib/src/model/ModelQueryBuilder.d.ts +48 -34
- package/lib/src/model/ModelQueryBuilder.js +163 -78
- 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.d.ts +3 -3
- package/lib/src/model/hydration.js +106 -36
- 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 +47 -0
- package/lib/src/model/query-sparql.js +336 -0
- package/lib/src/model/query-utils.d.ts +45 -0
- package/lib/src/model/query-utils.js +140 -0
- 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-pool.d.ts +39 -0
- package/lib/src/model/subscription-pool.js +119 -0
- package/lib/src/model/types.d.ts +3 -3
- package/lib/src/model/types.js +1 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +1 -17
- package/lib/src/perspectives/PerspectiveClient.js +5 -57
- package/lib/src/perspectives/PerspectiveProxy.d.ts +51 -30
- package/lib/src/perspectives/PerspectiveProxy.js +224 -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/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/language/Language.ts +48 -3
- package/src/model/Ad4mModel.test.ts +1515 -565
- package/src/model/Ad4mModel.ts +142 -102
- package/src/model/ModelQueryBuilder.ts +185 -86
- 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.ts +102 -39
- 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.ts +363 -0
- package/src/model/{surreal-utils.ts → query-utils.ts} +40 -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-pool.ts +163 -0
- package/src/model/types.ts +3 -3
- package/src/perspectives/PerspectiveClient.ts +5 -61
- package/src/perspectives/PerspectiveProxy.ts +226 -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/src/model/query-surreal.ts +0 -280
|
@@ -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.
|
|
@@ -187,31 +187,9 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
187
187
|
include(map: IncludeMap): ModelQueryBuilder<T>;
|
|
188
188
|
overrideModelClassName(className: string): ModelQueryBuilder<T>;
|
|
189
189
|
/**
|
|
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).
|
|
190
|
+
* Sets the query engine to use.
|
|
213
191
|
*/
|
|
214
|
-
|
|
192
|
+
engine(eng: 'sparql' | 'prolog'): ModelQueryBuilder<T>;
|
|
215
193
|
/**
|
|
216
194
|
* Executes the query once and returns the results.
|
|
217
195
|
*
|
|
@@ -225,6 +203,19 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
225
203
|
* ```
|
|
226
204
|
*/
|
|
227
205
|
get(): Promise<T[]>;
|
|
206
|
+
/**
|
|
207
|
+
* Executes the query once using SPARQL and returns the results.
|
|
208
|
+
*/
|
|
209
|
+
getSparql(): Promise<T[]>;
|
|
210
|
+
/**
|
|
211
|
+
* Shared SPARQL query execution logic used by both get() and getSparql().
|
|
212
|
+
*/
|
|
213
|
+
private executeSparqlQuery;
|
|
214
|
+
/**
|
|
215
|
+
* Groups raw SPARQL results and hydrates them into model instances.
|
|
216
|
+
* Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
|
|
217
|
+
*/
|
|
218
|
+
private processSparqlResult;
|
|
228
219
|
/**
|
|
229
220
|
* Returns the first matching instance, or `null` if none match.
|
|
230
221
|
*
|
|
@@ -244,7 +235,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
244
235
|
* Subscribes to the query and receives updates when results change.
|
|
245
236
|
*
|
|
246
237
|
* This method:
|
|
247
|
-
* 1. Creates and initializes a
|
|
238
|
+
* 1. Creates and initializes a SPARQL live query subscription (default)
|
|
248
239
|
* 2. Sets up the callback to process future updates
|
|
249
240
|
* 3. Returns the initial results immediately
|
|
250
241
|
*
|
|
@@ -268,10 +259,14 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
268
259
|
* ```
|
|
269
260
|
*
|
|
270
261
|
* @remarks
|
|
271
|
-
* By default, this uses
|
|
272
|
-
* Prolog subscriptions remain available via `.
|
|
262
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
263
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
273
264
|
*/
|
|
274
265
|
subscribe(callback: (results: T[]) => void): Promise<T[]>;
|
|
266
|
+
/**
|
|
267
|
+
* Subscribes to the query and receives updates using SPARQL.
|
|
268
|
+
*/
|
|
269
|
+
subscribeSparql(callback: (results: T[]) => void): Promise<T[]>;
|
|
275
270
|
/**
|
|
276
271
|
* Gets the total count of matching entities.
|
|
277
272
|
*
|
|
@@ -285,11 +280,16 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
285
280
|
* ```
|
|
286
281
|
*/
|
|
287
282
|
count(): Promise<number>;
|
|
283
|
+
/**
|
|
284
|
+
* Gets the total count of matching entities using SPARQL.
|
|
285
|
+
* Delegates to count() with SPARQL engine forced.
|
|
286
|
+
*/
|
|
287
|
+
countSparql(): Promise<number>;
|
|
288
288
|
/**
|
|
289
289
|
* Subscribes to count updates for matching entities.
|
|
290
290
|
*
|
|
291
291
|
* This method:
|
|
292
|
-
* 1. Creates and initializes a
|
|
292
|
+
* 1. Creates and initializes a SPARQL live query subscription for the count (default)
|
|
293
293
|
* 2. Sets up the callback to process future count updates
|
|
294
294
|
* 3. Returns the initial count immediately
|
|
295
295
|
*
|
|
@@ -313,10 +313,14 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
313
313
|
* ```
|
|
314
314
|
*
|
|
315
315
|
* @remarks
|
|
316
|
-
* By default, this uses
|
|
317
|
-
* Prolog subscriptions remain available via `.
|
|
316
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
317
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
318
318
|
*/
|
|
319
319
|
countSubscribe(callback: (count: number) => void): Promise<number>;
|
|
320
|
+
/**
|
|
321
|
+
* Subscribes to count updates using SPARQL.
|
|
322
|
+
*/
|
|
323
|
+
countSubscribeSparql(callback: (count: number) => void): Promise<number>;
|
|
320
324
|
/**
|
|
321
325
|
* Gets a page of results with pagination metadata.
|
|
322
326
|
*
|
|
@@ -333,11 +337,16 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
333
337
|
* ```
|
|
334
338
|
*/
|
|
335
339
|
paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
|
|
340
|
+
/**
|
|
341
|
+
* Gets a page of results using SPARQL.
|
|
342
|
+
* Delegates to paginate() with SPARQL engine forced.
|
|
343
|
+
*/
|
|
344
|
+
paginateSparql(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
|
|
336
345
|
/**
|
|
337
346
|
* Subscribes to paginated results updates.
|
|
338
347
|
*
|
|
339
348
|
* This method:
|
|
340
|
-
* 1. Creates and initializes a
|
|
349
|
+
* 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
|
|
341
350
|
* 2. Sets up the callback to process future page updates
|
|
342
351
|
* 3. Returns the initial page immediately
|
|
343
352
|
*
|
|
@@ -363,8 +372,13 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
363
372
|
* ```
|
|
364
373
|
*
|
|
365
374
|
* @remarks
|
|
366
|
-
* By default, this uses
|
|
367
|
-
* Prolog subscriptions remain available via `.
|
|
375
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
376
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
368
377
|
*/
|
|
369
378
|
paginateSubscribe(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
|
|
379
|
+
/**
|
|
380
|
+
* Subscribes to paginated results updates using SPARQL.
|
|
381
|
+
* Delegates to paginateSubscribe() with SPARQL engine forced.
|
|
382
|
+
*/
|
|
383
|
+
paginateSubscribeSparql(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
|
|
370
384
|
}
|
|
@@ -4,6 +4,8 @@
|
|
|
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 } from "./query-sparql";
|
|
8
|
+
import { pooledSubscribe } from "./subscription-pool";
|
|
7
9
|
/** Query builder for Ad4mModel queries.
|
|
8
10
|
* Allows building queries with a fluent interface and either running them once
|
|
9
11
|
* or subscribing to updates.
|
|
@@ -28,7 +30,7 @@ export class ModelQueryBuilder {
|
|
|
28
30
|
constructor(perspective, ctor, query) {
|
|
29
31
|
this.queryParams = {};
|
|
30
32
|
this.modelClassName = null;
|
|
31
|
-
this.
|
|
33
|
+
this.engineFlag = 'sparql';
|
|
32
34
|
this.perspective = perspective;
|
|
33
35
|
this.ctor = ctor;
|
|
34
36
|
if (query)
|
|
@@ -236,32 +238,10 @@ export class ModelQueryBuilder {
|
|
|
236
238
|
return this;
|
|
237
239
|
}
|
|
238
240
|
/**
|
|
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).
|
|
241
|
+
* Sets the query engine to use.
|
|
262
242
|
*/
|
|
263
|
-
|
|
264
|
-
this.
|
|
243
|
+
engine(eng) {
|
|
244
|
+
this.engineFlag = eng;
|
|
265
245
|
return this;
|
|
266
246
|
}
|
|
267
247
|
/**
|
|
@@ -278,10 +258,8 @@ export class ModelQueryBuilder {
|
|
|
278
258
|
*/
|
|
279
259
|
async get() {
|
|
280
260
|
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));
|
|
261
|
+
if (this.engineFlag === 'sparql') {
|
|
262
|
+
results = await this.executeSparqlQuery();
|
|
285
263
|
}
|
|
286
264
|
else {
|
|
287
265
|
const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
@@ -290,6 +268,29 @@ export class ModelQueryBuilder {
|
|
|
290
268
|
}
|
|
291
269
|
return results;
|
|
292
270
|
}
|
|
271
|
+
/**
|
|
272
|
+
* Executes the query once using SPARQL and returns the results.
|
|
273
|
+
*/
|
|
274
|
+
async getSparql() {
|
|
275
|
+
return this.executeSparqlQuery();
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Shared SPARQL query execution logic used by both get() and getSparql().
|
|
279
|
+
*/
|
|
280
|
+
async executeSparqlQuery() {
|
|
281
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
282
|
+
const rawResult = await this.perspective.querySparql(sparqlQuery);
|
|
283
|
+
const { results } = await this.processSparqlResult(rawResult);
|
|
284
|
+
return results;
|
|
285
|
+
}
|
|
286
|
+
/**
|
|
287
|
+
* Groups raw SPARQL results and hydrates them into model instances.
|
|
288
|
+
* Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
|
|
289
|
+
*/
|
|
290
|
+
async processSparqlResult(rawResult, queryOverride) {
|
|
291
|
+
const grouped = groupSPARQLResults(Array.isArray(rawResult) ? rawResult : []);
|
|
292
|
+
return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped);
|
|
293
|
+
}
|
|
293
294
|
/**
|
|
294
295
|
* Returns the first matching instance, or `null` if none match.
|
|
295
296
|
*
|
|
@@ -313,7 +314,7 @@ export class ModelQueryBuilder {
|
|
|
313
314
|
* Subscribes to the query and receives updates when results change.
|
|
314
315
|
*
|
|
315
316
|
* This method:
|
|
316
|
-
* 1. Creates and initializes a
|
|
317
|
+
* 1. Creates and initializes a SPARQL live query subscription (default)
|
|
317
318
|
* 2. Sets up the callback to process future updates
|
|
318
319
|
* 3. Returns the initial results immediately
|
|
319
320
|
*
|
|
@@ -337,26 +338,40 @@ export class ModelQueryBuilder {
|
|
|
337
338
|
* ```
|
|
338
339
|
*
|
|
339
340
|
* @remarks
|
|
340
|
-
* By default, this uses
|
|
341
|
-
* Prolog subscriptions remain available via `.
|
|
341
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
342
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
342
343
|
*/
|
|
343
344
|
async subscribe(callback) {
|
|
344
345
|
// Clean up any existing subscription
|
|
345
346
|
this.dispose();
|
|
346
347
|
const ctor = this.ctor;
|
|
347
|
-
if (this.
|
|
348
|
-
const
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
348
|
+
if (this.engineFlag === 'sparql') {
|
|
349
|
+
const sparqlQuery = await ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
350
|
+
// Track last emitted result fingerprint to suppress duplicate callbacks
|
|
351
|
+
let lastResultFingerprint = null;
|
|
352
|
+
const buildFingerprint = (results) => {
|
|
353
|
+
if (results.length === 0)
|
|
354
|
+
return '0:';
|
|
355
|
+
const ids = results.map((r) => r.id || '').sort().join(',');
|
|
356
|
+
const ts = results.map((r) => r.updatedAt || r.timestamp || '').join(',');
|
|
357
|
+
return `${results.length}:${ids}:${ts}`;
|
|
353
358
|
};
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
359
|
+
const hydrate = async (rawResult) => {
|
|
360
|
+
const { results } = await this.processSparqlResult(rawResult);
|
|
361
|
+
return results;
|
|
362
|
+
};
|
|
363
|
+
const pooled = await pooledSubscribe(this.perspective, sparqlQuery, hydrate, (hydratedResults) => {
|
|
364
|
+
const fp = buildFingerprint(hydratedResults);
|
|
365
|
+
if (fp === lastResultFingerprint)
|
|
366
|
+
return;
|
|
367
|
+
lastResultFingerprint = fp;
|
|
368
|
+
callback(hydratedResults);
|
|
369
|
+
});
|
|
370
|
+
// Store dispose function as subscription
|
|
371
|
+
this.currentSubscription = { dispose: pooled.dispose };
|
|
372
|
+
const initialResults = pooled.initialResult;
|
|
373
|
+
lastResultFingerprint = buildFingerprint(initialResults);
|
|
374
|
+
return initialResults;
|
|
360
375
|
}
|
|
361
376
|
else {
|
|
362
377
|
const query = await ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
|
|
@@ -367,11 +382,26 @@ export class ModelQueryBuilder {
|
|
|
367
382
|
};
|
|
368
383
|
this.currentSubscription.onResult(processResults);
|
|
369
384
|
const { results } = await ctor.instancesFromPrologResult(this.perspective, this.queryParams, this.currentSubscription.result);
|
|
370
|
-
//
|
|
371
|
-
callback(results);
|
|
385
|
+
// Initial results returned via Promise only — callback is for subsequent updates
|
|
372
386
|
return results;
|
|
373
387
|
}
|
|
374
388
|
}
|
|
389
|
+
/**
|
|
390
|
+
* Subscribes to the query and receives updates using SPARQL.
|
|
391
|
+
*/
|
|
392
|
+
async subscribeSparql(callback) {
|
|
393
|
+
this.dispose();
|
|
394
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
395
|
+
this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
|
|
396
|
+
const processResults = async (result) => {
|
|
397
|
+
const { results } = await this.processSparqlResult(result);
|
|
398
|
+
callback(results);
|
|
399
|
+
};
|
|
400
|
+
this.currentSubscription.onResult(processResults);
|
|
401
|
+
const { results } = await this.processSparqlResult(this.currentSubscription.result);
|
|
402
|
+
// Initial results returned via Promise only — callback is for subsequent updates
|
|
403
|
+
return results;
|
|
404
|
+
}
|
|
375
405
|
/**
|
|
376
406
|
* Gets the total count of matching entities.
|
|
377
407
|
*
|
|
@@ -385,13 +415,10 @@ export class ModelQueryBuilder {
|
|
|
385
415
|
* ```
|
|
386
416
|
*/
|
|
387
417
|
async count() {
|
|
388
|
-
if (this.
|
|
389
|
-
const
|
|
390
|
-
const
|
|
391
|
-
|
|
392
|
-
// (e.g., gt, gte, lt, lte, between, contains on properties and author/timestamp)
|
|
393
|
-
// This ensures count() returns the same number as get().length
|
|
394
|
-
const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
|
|
418
|
+
if (this.engineFlag === 'sparql') {
|
|
419
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
420
|
+
const rawResult = await this.perspective.querySparql(sparqlQuery);
|
|
421
|
+
const { totalCount } = await this.processSparqlResult(rawResult);
|
|
395
422
|
return totalCount;
|
|
396
423
|
}
|
|
397
424
|
else {
|
|
@@ -400,11 +427,25 @@ export class ModelQueryBuilder {
|
|
|
400
427
|
return result?.[0]?.TotalCount || 0;
|
|
401
428
|
}
|
|
402
429
|
}
|
|
430
|
+
/**
|
|
431
|
+
* Gets the total count of matching entities using SPARQL.
|
|
432
|
+
* Delegates to count() with SPARQL engine forced.
|
|
433
|
+
*/
|
|
434
|
+
async countSparql() {
|
|
435
|
+
const prev = this.engineFlag;
|
|
436
|
+
this.engineFlag = 'sparql';
|
|
437
|
+
try {
|
|
438
|
+
return await this.count();
|
|
439
|
+
}
|
|
440
|
+
finally {
|
|
441
|
+
this.engineFlag = prev;
|
|
442
|
+
}
|
|
443
|
+
}
|
|
403
444
|
/**
|
|
404
445
|
* Subscribes to count updates for matching entities.
|
|
405
446
|
*
|
|
406
447
|
* This method:
|
|
407
|
-
* 1. Creates and initializes a
|
|
448
|
+
* 1. Creates and initializes a SPARQL live query subscription for the count (default)
|
|
408
449
|
* 2. Sets up the callback to process future count updates
|
|
409
450
|
* 3. Returns the initial count immediately
|
|
410
451
|
*
|
|
@@ -428,22 +469,22 @@ export class ModelQueryBuilder {
|
|
|
428
469
|
* ```
|
|
429
470
|
*
|
|
430
471
|
* @remarks
|
|
431
|
-
* By default, this uses
|
|
432
|
-
* Prolog subscriptions remain available via `.
|
|
472
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
473
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
433
474
|
*/
|
|
434
475
|
async countSubscribe(callback) {
|
|
435
476
|
// Clean up any existing subscription
|
|
436
477
|
this.dispose();
|
|
437
|
-
if (this.
|
|
438
|
-
const
|
|
439
|
-
this.currentSubscription = await this.perspective.
|
|
478
|
+
if (this.engineFlag === 'sparql') {
|
|
479
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
480
|
+
this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
|
|
440
481
|
const processResults = async (result) => {
|
|
441
|
-
const { totalCount } = await this.
|
|
482
|
+
const { totalCount } = await this.processSparqlResult(result);
|
|
442
483
|
callback(totalCount);
|
|
443
484
|
};
|
|
444
485
|
this.currentSubscription.onResult(processResults);
|
|
445
|
-
const { totalCount } = await this.
|
|
446
|
-
callback
|
|
486
|
+
const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
|
|
487
|
+
// Initial count returned via Promise — callback for updates only
|
|
447
488
|
return totalCount;
|
|
448
489
|
}
|
|
449
490
|
else {
|
|
@@ -455,10 +496,26 @@ export class ModelQueryBuilder {
|
|
|
455
496
|
};
|
|
456
497
|
this.currentSubscription.onResult(processResults);
|
|
457
498
|
const initialCount = this.currentSubscription.result?.[0]?.TotalCount || 0;
|
|
458
|
-
callback
|
|
499
|
+
// Initial count returned via Promise — callback for subsequent updates only
|
|
459
500
|
return initialCount;
|
|
460
501
|
}
|
|
461
502
|
}
|
|
503
|
+
/**
|
|
504
|
+
* Subscribes to count updates using SPARQL.
|
|
505
|
+
*/
|
|
506
|
+
async countSubscribeSparql(callback) {
|
|
507
|
+
this.dispose();
|
|
508
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
|
|
509
|
+
this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
|
|
510
|
+
const processResults = async (result) => {
|
|
511
|
+
const { totalCount } = await this.processSparqlResult(result);
|
|
512
|
+
callback(totalCount);
|
|
513
|
+
};
|
|
514
|
+
this.currentSubscription.onResult(processResults);
|
|
515
|
+
const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
|
|
516
|
+
// Initial count returned via Promise — callback for updates only
|
|
517
|
+
return totalCount;
|
|
518
|
+
}
|
|
462
519
|
/**
|
|
463
520
|
* Gets a page of results with pagination metadata.
|
|
464
521
|
*
|
|
@@ -476,10 +533,10 @@ export class ModelQueryBuilder {
|
|
|
476
533
|
*/
|
|
477
534
|
async paginate(pageSize, pageNumber) {
|
|
478
535
|
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 } =
|
|
536
|
+
if (this.engineFlag === 'sparql') {
|
|
537
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
|
|
538
|
+
const result = await this.perspective.querySparql(sparqlQuery);
|
|
539
|
+
const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
|
|
483
540
|
return { results, totalCount, pageSize, pageNumber };
|
|
484
541
|
}
|
|
485
542
|
else {
|
|
@@ -489,11 +546,25 @@ export class ModelQueryBuilder {
|
|
|
489
546
|
return { results, totalCount, pageSize, pageNumber };
|
|
490
547
|
}
|
|
491
548
|
}
|
|
549
|
+
/**
|
|
550
|
+
* Gets a page of results using SPARQL.
|
|
551
|
+
* Delegates to paginate() with SPARQL engine forced.
|
|
552
|
+
*/
|
|
553
|
+
async paginateSparql(pageSize, pageNumber) {
|
|
554
|
+
const prev = this.engineFlag;
|
|
555
|
+
this.engineFlag = 'sparql';
|
|
556
|
+
try {
|
|
557
|
+
return await this.paginate(pageSize, pageNumber);
|
|
558
|
+
}
|
|
559
|
+
finally {
|
|
560
|
+
this.engineFlag = prev;
|
|
561
|
+
}
|
|
562
|
+
}
|
|
492
563
|
/**
|
|
493
564
|
* Subscribes to paginated results updates.
|
|
494
565
|
*
|
|
495
566
|
* This method:
|
|
496
|
-
* 1. Creates and initializes a
|
|
567
|
+
* 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
|
|
497
568
|
* 2. Sets up the callback to process future page updates
|
|
498
569
|
* 3. Returns the initial page immediately
|
|
499
570
|
*
|
|
@@ -519,24 +590,24 @@ export class ModelQueryBuilder {
|
|
|
519
590
|
* ```
|
|
520
591
|
*
|
|
521
592
|
* @remarks
|
|
522
|
-
* By default, this uses
|
|
523
|
-
* Prolog subscriptions remain available via `.
|
|
593
|
+
* By default, this uses SPARQL live queries for real-time updates.
|
|
594
|
+
* Prolog subscriptions remain available via `.useSPARQL(false)`.
|
|
524
595
|
*/
|
|
525
596
|
async paginateSubscribe(pageSize, pageNumber, callback) {
|
|
526
597
|
// Clean up any existing subscription
|
|
527
598
|
this.dispose();
|
|
528
599
|
const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
|
|
529
|
-
if (this.
|
|
530
|
-
const
|
|
531
|
-
this.currentSubscription = await this.perspective.
|
|
600
|
+
if (this.engineFlag === 'sparql') {
|
|
601
|
+
const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
|
|
602
|
+
this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
|
|
532
603
|
const processResults = async (result) => {
|
|
533
|
-
const { results, totalCount } =
|
|
604
|
+
const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
|
|
534
605
|
callback({ results, totalCount, pageSize, pageNumber });
|
|
535
606
|
};
|
|
536
607
|
this.currentSubscription.onResult(processResults);
|
|
537
|
-
const { results, totalCount } =
|
|
608
|
+
const { results, totalCount } = await this.processSparqlResult(this.currentSubscription.result, paginationQuery);
|
|
538
609
|
const initialPage = { results, totalCount, pageSize, pageNumber };
|
|
539
|
-
callback
|
|
610
|
+
// Initial page returned via Promise — callback for subsequent updates only
|
|
540
611
|
return initialPage;
|
|
541
612
|
}
|
|
542
613
|
else {
|
|
@@ -549,8 +620,22 @@ export class ModelQueryBuilder {
|
|
|
549
620
|
this.currentSubscription.onResult(processResults);
|
|
550
621
|
const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result));
|
|
551
622
|
const initialPrologPage = { results, totalCount, pageSize, pageNumber };
|
|
552
|
-
callback
|
|
623
|
+
// Initial page returned via Promise — callback for subsequent updates only
|
|
553
624
|
return initialPrologPage;
|
|
554
625
|
}
|
|
555
626
|
}
|
|
627
|
+
/**
|
|
628
|
+
* Subscribes to paginated results updates using SPARQL.
|
|
629
|
+
* Delegates to paginateSubscribe() with SPARQL engine forced.
|
|
630
|
+
*/
|
|
631
|
+
async paginateSubscribeSparql(pageSize, pageNumber, callback) {
|
|
632
|
+
const prev = this.engineFlag;
|
|
633
|
+
this.engineFlag = 'sparql';
|
|
634
|
+
try {
|
|
635
|
+
return await this.paginateSubscribe(pageSize, pageNumber, callback);
|
|
636
|
+
}
|
|
637
|
+
finally {
|
|
638
|
+
this.engineFlag = prev;
|
|
639
|
+
}
|
|
640
|
+
}
|
|
556
641
|
}
|
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
|
}
|
|
@@ -19,7 +19,7 @@ export interface RelationMetadataEntry {
|
|
|
19
19
|
maxCount?: number;
|
|
20
20
|
local?: boolean;
|
|
21
21
|
/**
|
|
22
|
-
* Custom
|
|
22
|
+
* Custom getter to resolve the relation values.
|
|
23
23
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
24
24
|
*/
|
|
25
25
|
getter?: string;
|
|
@@ -39,13 +39,19 @@ export interface RelationMetadataEntry {
|
|
|
39
39
|
/**
|
|
40
40
|
* Retrieve property metadata for a given class constructor.
|
|
41
41
|
* Walks the prototype chain so subclass decorators compose with parent decorators.
|
|
42
|
+
* Results are memoised per class constructor.
|
|
42
43
|
*/
|
|
43
44
|
export declare function getPropertiesMetadata(ctor: Function): Record<string, PropertyMetadataEntry>;
|
|
44
45
|
/**
|
|
45
46
|
* Retrieve relation metadata for a given class constructor.
|
|
46
47
|
* Walks the prototype chain so subclass decorators compose with parent decorators.
|
|
48
|
+
* Results are memoised per class constructor.
|
|
47
49
|
*/
|
|
48
50
|
export declare function getRelationsMetadata(ctor: Function): Record<string, RelationMetadataEntry>;
|
|
51
|
+
/**
|
|
52
|
+
* Get or compute memoised SHACL for a class. Used by @Model decorator.
|
|
53
|
+
*/
|
|
54
|
+
export declare function getMemoizedSHACL(target: Function, compute: () => any): any;
|
|
49
55
|
/**
|
|
50
56
|
* Programmatically register property metadata for a given constructor.
|
|
51
57
|
* Used by `fromJSONSchema()` and other dynamic model builders.
|
|
@@ -72,7 +78,7 @@ export interface Ad4mModelLike {
|
|
|
72
78
|
*
|
|
73
79
|
* Inspects the target class's property metadata to derive:
|
|
74
80
|
* - `conformanceConditions`: Structured, DB-agnostic conditions (flag & required checks)
|
|
75
|
-
* - `getter`: Pre-computed
|
|
81
|
+
* - `getter`: Pre-computed graph traversal expression that traverses outgoing links and filters
|
|
76
82
|
* target nodes to only those conforming to the target shape.
|
|
77
83
|
*
|
|
78
84
|
* @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
|
|
@@ -114,9 +120,9 @@ export interface PropertyOptions {
|
|
|
114
120
|
*/
|
|
115
121
|
prologSetter?: string;
|
|
116
122
|
/**
|
|
117
|
-
* Custom
|
|
123
|
+
* Custom getter to resolve the property value. Use this for custom graph traversals.
|
|
118
124
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
119
|
-
* Example: "
|
|
125
|
+
* Example: "SELECT ?target WHERE { <Base> <flux://has_reply> ?target . } LIMIT 1"
|
|
120
126
|
*/
|
|
121
127
|
getter?: string;
|
|
122
128
|
/**
|
|
@@ -294,7 +300,7 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
|
|
|
294
300
|
* Properties are optional by default. When a model instance is created without
|
|
295
301
|
* providing a value for an optional property, no link is added to the graph.
|
|
296
302
|
* Set `required: true` explicitly when a property must always be present (this
|
|
297
|
-
* also adds a `"literal
|
|
303
|
+
* also adds a `"literal:string:uninitialized"` sentinel as the initial value
|
|
298
304
|
* so that the SDNA constructor creates a placeholder link).
|
|
299
305
|
*
|
|
300
306
|
* @example
|
|
@@ -333,7 +339,7 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
|
|
|
333
339
|
* @param {PropertyOptions} opts - Property configuration
|
|
334
340
|
* @param {string} opts.through - The predicate URI for the property
|
|
335
341
|
* @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
|
|
336
|
-
* @param {string} [opts.initial] - Initial value (defaults to "literal
|
|
342
|
+
* @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
|
|
337
343
|
* @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
|
|
338
344
|
* @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
|
|
339
345
|
* @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
|
|
@@ -410,9 +416,9 @@ export interface RelationOptions {
|
|
|
410
416
|
* Cannot be combined with `getter`. */
|
|
411
417
|
target?: () => Ad4mModelLike;
|
|
412
418
|
/**
|
|
413
|
-
* Custom
|
|
419
|
+
* Custom getter to resolve the relation values. Use this for custom graph traversals.
|
|
414
420
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
415
|
-
* Example: "
|
|
421
|
+
* Example: "SELECT ?target WHERE { ?target <flux://has_reply> <Base> . }"
|
|
416
422
|
*
|
|
417
423
|
* Mutually exclusive with `through` and `target`. When `getter` is provided the
|
|
418
424
|
* relation is read-only (no adder/remover actions are generated).
|