@coasys/ad4m 0.10.1 → 0.11.0
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 +1716 -87
- package/lib/index.js +1716 -87
- package/lib/src/model/Ad4mModel.d.ts +423 -9
- package/lib/src/model/Ad4mModel.js +1499 -61
- package/lib/src/model/Ad4mModel.test.d.ts +1 -0
- package/lib/src/model/Ad4mModel.test.js +1325 -0
- package/lib/src/perspectives/PerspectiveClient.d.ts +17 -0
- package/lib/src/perspectives/PerspectiveClient.js +61 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +52 -1
- package/lib/src/perspectives/PerspectiveProxy.js +157 -28
- package/lib/src/perspectives/PerspectiveResolver.d.ts +1 -0
- package/lib/src/perspectives/PerspectiveResolver.js +11 -0
- package/lib/src/schema.gql +1 -0
- package/lib/src/typeDefs.js +1 -0
- package/package.json +1 -1
- package/src/model/Ad4mModel.test.ts +1476 -0
- package/src/model/Ad4mModel.ts +1758 -87
- package/src/perspectives/PerspectiveClient.ts +67 -0
- package/src/perspectives/PerspectiveProxy.ts +175 -35
- package/src/perspectives/PerspectiveResolver.ts +8 -0
|
@@ -1,4 +1,44 @@
|
|
|
1
1
|
import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
2
|
+
import { PropertyOptions } from "./decorators";
|
|
3
|
+
interface JSONSchemaProperty {
|
|
4
|
+
type: string | string[];
|
|
5
|
+
items?: JSONSchemaProperty;
|
|
6
|
+
properties?: {
|
|
7
|
+
[key: string]: JSONSchemaProperty;
|
|
8
|
+
};
|
|
9
|
+
required?: string[];
|
|
10
|
+
"x-ad4m"?: {
|
|
11
|
+
through?: string;
|
|
12
|
+
resolveLanguage?: string;
|
|
13
|
+
local?: boolean;
|
|
14
|
+
writable?: boolean;
|
|
15
|
+
initial?: string;
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
interface JSONSchema {
|
|
19
|
+
$schema?: string;
|
|
20
|
+
title?: string;
|
|
21
|
+
$id?: string;
|
|
22
|
+
type?: string;
|
|
23
|
+
properties?: {
|
|
24
|
+
[key: string]: JSONSchemaProperty;
|
|
25
|
+
};
|
|
26
|
+
required?: string[];
|
|
27
|
+
"x-ad4m"?: {
|
|
28
|
+
namespace?: string;
|
|
29
|
+
className?: string;
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
interface JSONSchemaToModelOptions {
|
|
33
|
+
name: string;
|
|
34
|
+
namespace?: string;
|
|
35
|
+
predicateTemplate?: string;
|
|
36
|
+
predicateGenerator?: (title: string, property: string) => string;
|
|
37
|
+
propertyMapping?: Record<string, string>;
|
|
38
|
+
resolveLanguage?: string;
|
|
39
|
+
local?: boolean;
|
|
40
|
+
propertyOptions?: Record<string, Partial<PropertyOptions>>;
|
|
41
|
+
}
|
|
2
42
|
type ValueTuple = [name: string, value: any, resolve?: boolean];
|
|
3
43
|
type WhereOps = {
|
|
4
44
|
not: string | number | boolean | string[] | number[];
|
|
@@ -7,6 +47,7 @@ type WhereOps = {
|
|
|
7
47
|
lte: number;
|
|
8
48
|
gt: number;
|
|
9
49
|
gte: number;
|
|
50
|
+
contains: string | number;
|
|
10
51
|
};
|
|
11
52
|
type WhereCondition = string | number | boolean | string[] | number[] | {
|
|
12
53
|
[K in keyof WhereOps]?: WhereOps[K];
|
|
@@ -42,6 +83,60 @@ export type PaginationResult<T> = {
|
|
|
42
83
|
pageSize: number;
|
|
43
84
|
pageNumber: number;
|
|
44
85
|
};
|
|
86
|
+
/**
|
|
87
|
+
* Metadata for a single property extracted from decorators.
|
|
88
|
+
*/
|
|
89
|
+
export interface PropertyMetadata {
|
|
90
|
+
/** The property name */
|
|
91
|
+
name: string;
|
|
92
|
+
/** The predicate URI (through value) */
|
|
93
|
+
predicate: string;
|
|
94
|
+
/** Whether the property is required */
|
|
95
|
+
required: boolean;
|
|
96
|
+
/** Whether the property is writable */
|
|
97
|
+
writable: boolean;
|
|
98
|
+
/** Initial value if specified */
|
|
99
|
+
initial?: string;
|
|
100
|
+
/** Language for resolution (e.g., "literal") */
|
|
101
|
+
resolveLanguage?: string;
|
|
102
|
+
/** Custom Prolog getter code */
|
|
103
|
+
getter?: string;
|
|
104
|
+
/** Custom Prolog setter code */
|
|
105
|
+
setter?: string;
|
|
106
|
+
/** Whether stored locally only */
|
|
107
|
+
local?: boolean;
|
|
108
|
+
/** Transform function */
|
|
109
|
+
transform?: (value: any) => any;
|
|
110
|
+
/** Whether this is a flag property */
|
|
111
|
+
flag?: boolean;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Metadata for a single collection extracted from decorators.
|
|
115
|
+
*/
|
|
116
|
+
export interface CollectionMetadata {
|
|
117
|
+
/** The collection name */
|
|
118
|
+
name: string;
|
|
119
|
+
/** The predicate URI (through value) */
|
|
120
|
+
predicate: string;
|
|
121
|
+
/** Filter conditions */
|
|
122
|
+
where?: {
|
|
123
|
+
isInstance?: any;
|
|
124
|
+
condition?: string;
|
|
125
|
+
};
|
|
126
|
+
/** Whether stored locally only */
|
|
127
|
+
local?: boolean;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Complete model metadata extracted from decorators.
|
|
131
|
+
*/
|
|
132
|
+
export interface ModelMetadata {
|
|
133
|
+
/** The model class name from @ModelOptions */
|
|
134
|
+
className: string;
|
|
135
|
+
/** Map of property name to metadata */
|
|
136
|
+
properties: Record<string, PropertyMetadata>;
|
|
137
|
+
/** Map of collection name to metadata */
|
|
138
|
+
collections: Record<string, CollectionMetadata>;
|
|
139
|
+
}
|
|
45
140
|
/**
|
|
46
141
|
* Base class for defining data models in AD4M.
|
|
47
142
|
*
|
|
@@ -147,6 +242,45 @@ export declare class Ad4mModel {
|
|
|
147
242
|
timestamp: string;
|
|
148
243
|
private static classNamesByClass;
|
|
149
244
|
static getClassName(perspective: PerspectiveProxy): Promise<string>;
|
|
245
|
+
/**
|
|
246
|
+
* Extracts metadata from decorators for query building.
|
|
247
|
+
*
|
|
248
|
+
* @description
|
|
249
|
+
* This method reads the metadata stored by decorators (@Property, @Collection, etc.)
|
|
250
|
+
* and returns it in a structured format that's easier to work with for query builders
|
|
251
|
+
* and other systems that need to introspect model structure.
|
|
252
|
+
*
|
|
253
|
+
* The metadata includes:
|
|
254
|
+
* - Class name from @ModelOptions
|
|
255
|
+
* - Property metadata (predicates, types, constraints, etc.)
|
|
256
|
+
* - Collection metadata (predicates, filters, etc.)
|
|
257
|
+
*
|
|
258
|
+
* For models created via `fromJSONSchema()`, this method will derive metadata from
|
|
259
|
+
* the stored `__properties` and `__collections` structures that were populated during
|
|
260
|
+
* the dynamic class creation. If these structures are empty but a JSON schema was
|
|
261
|
+
* attached to the class, it can fall back to deriving metadata from that schema.
|
|
262
|
+
*
|
|
263
|
+
* @returns Structured metadata object containing className, properties, and collections
|
|
264
|
+
* @throws Error if the class doesn't have @ModelOptions decorator
|
|
265
|
+
*
|
|
266
|
+
* @example
|
|
267
|
+
* ```typescript
|
|
268
|
+
* @ModelOptions({ name: "Recipe" })
|
|
269
|
+
* class Recipe extends Ad4mModel {
|
|
270
|
+
* @Property({ through: "recipe://name", resolveLanguage: "literal" })
|
|
271
|
+
* name: string = "";
|
|
272
|
+
*
|
|
273
|
+
* @Collection({ through: "recipe://ingredient" })
|
|
274
|
+
* ingredients: string[] = [];
|
|
275
|
+
* }
|
|
276
|
+
*
|
|
277
|
+
* const metadata = Recipe.getModelMetadata();
|
|
278
|
+
* console.log(metadata.className); // "Recipe"
|
|
279
|
+
* console.log(metadata.properties.name.predicate); // "recipe://name"
|
|
280
|
+
* console.log(metadata.collections.ingredients.predicate); // "recipe://ingredient"
|
|
281
|
+
* ```
|
|
282
|
+
*/
|
|
283
|
+
static getModelMetadata(): ModelMetadata;
|
|
150
284
|
/**
|
|
151
285
|
* Constructs a new model instance.
|
|
152
286
|
*
|
|
@@ -179,20 +313,168 @@ export declare class Ad4mModel {
|
|
|
179
313
|
static assignValuesToInstance(perspective: PerspectiveProxy, instance: Ad4mModel, values: ValueTuple[]): Promise<void>;
|
|
180
314
|
private getData;
|
|
181
315
|
static queryToProlog(perspective: PerspectiveProxy, query: Query, modelClassName?: string | null): Promise<string>;
|
|
316
|
+
/**
|
|
317
|
+
* Generates a SurrealQL query from a Query object.
|
|
318
|
+
*
|
|
319
|
+
* @description
|
|
320
|
+
* This method translates high-level query parameters into a SurrealQL query string
|
|
321
|
+
* that can be executed against the SurrealDB backend. Unlike Prolog queries which
|
|
322
|
+
* operate on SDNA-aware predicates, SurrealQL queries operate directly on raw links
|
|
323
|
+
* stored in SurrealDB.
|
|
324
|
+
*
|
|
325
|
+
* The generated query uses a CTE (Common Table Expression) pattern:
|
|
326
|
+
* 1. First, identify candidate base expressions by filtering links based on where conditions
|
|
327
|
+
* 2. Then, for each candidate base, resolve properties and collections via subqueries
|
|
328
|
+
* 3. Finally, apply ordering, pagination (LIMIT/START) at the SQL level
|
|
329
|
+
*
|
|
330
|
+
* Key architectural notes:
|
|
331
|
+
* - SurrealDB stores only raw links (source, predicate, target, author, timestamp)
|
|
332
|
+
* - No SDNA knowledge at the database level
|
|
333
|
+
* - Properties are resolved via subqueries that look for links with specific predicates
|
|
334
|
+
* - Collections are similar but return multiple values instead of one
|
|
335
|
+
* - Special fields (base, author, timestamp) are accessed directly, not via subqueries
|
|
336
|
+
*
|
|
337
|
+
* @param perspective - The perspective to query (used for metadata extraction)
|
|
338
|
+
* @param query - Query parameters (where, order, limit, offset, properties, collections)
|
|
339
|
+
* @returns Complete SurrealQL query string ready for execution
|
|
340
|
+
*
|
|
341
|
+
* @example
|
|
342
|
+
* ```typescript
|
|
343
|
+
* const query = Recipe.queryToSurrealQL(perspective, {
|
|
344
|
+
* where: { name: "Pasta", rating: { gt: 4 } },
|
|
345
|
+
* order: { timestamp: "DESC" },
|
|
346
|
+
* limit: 10
|
|
347
|
+
* });
|
|
348
|
+
* // Returns: SELECT source AS base, array::first(target[WHERE predicate = ...]) AS name, ...
|
|
349
|
+
* // FROM link WHERE ... GROUP BY source ORDER BY timestamp DESC LIMIT 10
|
|
350
|
+
* ```
|
|
351
|
+
*/
|
|
352
|
+
static queryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string>;
|
|
353
|
+
/**
|
|
354
|
+
* Builds the WHERE clause for SurrealQL queries using graph traversal syntax.
|
|
355
|
+
*
|
|
356
|
+
* @description
|
|
357
|
+
* Translates where conditions into graph traversal filters: `->link[WHERE ...]`
|
|
358
|
+
* This is more efficient than nested SELECTs because SurrealDB can optimize graph traversals.
|
|
359
|
+
*
|
|
360
|
+
* Handles several condition types:
|
|
361
|
+
* - Simple equality: `{ name: "Pasta" }` → `->link[WHERE predicate = 'X' AND out.uri = 'Pasta']`
|
|
362
|
+
* - Arrays (IN clause): `{ name: ["Pasta", "Pizza"] }` → `->link[WHERE predicate = 'X' AND out.uri IN [...]]`
|
|
363
|
+
* - NOT operators: Use `NOT` prefix
|
|
364
|
+
* - Comparison operators (gt, gte, lt, lte, etc.): Handled in post-query JavaScript filtering
|
|
365
|
+
* - Special fields: base uses `uri` directly, author/timestamp handled post-query
|
|
366
|
+
*
|
|
367
|
+
* @param metadata - Model metadata containing property predicates
|
|
368
|
+
* @param where - Where conditions from the query
|
|
369
|
+
* @returns Graph traversal WHERE clause filters, or empty string if no conditions
|
|
370
|
+
*
|
|
371
|
+
* @private
|
|
372
|
+
*/
|
|
373
|
+
private static buildGraphTraversalWhereClause;
|
|
374
|
+
/**
|
|
375
|
+
* Builds the WHERE clause for SurrealQL queries.
|
|
376
|
+
*
|
|
377
|
+
* @description
|
|
378
|
+
* Translates the where conditions from the Query object into SurrealQL WHERE clause fragments.
|
|
379
|
+
* For each property filter, generates a subquery that checks for links with the appropriate
|
|
380
|
+
* predicate and target value.
|
|
381
|
+
*
|
|
382
|
+
* Handles several condition types:
|
|
383
|
+
* - Simple equality: `{ name: "Pasta" }` → subquery checking for predicate and target match
|
|
384
|
+
* - Arrays (IN clause): `{ name: ["Pasta", "Pizza"] }` → target IN [...]
|
|
385
|
+
* - Operators: `{ rating: { gt: 4 } }` → target > '4'
|
|
386
|
+
* - gt, gte, lt, lte: comparison operators
|
|
387
|
+
* - not: negation (single value or array)
|
|
388
|
+
* - between: range check
|
|
389
|
+
* - contains: substring/element check (uses SurrealQL CONTAINS)
|
|
390
|
+
* - Special fields: base, author, timestamp are accessed directly, not via subqueries
|
|
391
|
+
*
|
|
392
|
+
* All conditions are joined with AND.
|
|
393
|
+
*
|
|
394
|
+
* @param metadata - Model metadata containing property predicates
|
|
395
|
+
* @param where - Where conditions from the query
|
|
396
|
+
* @returns WHERE clause string (without the "WHERE" keyword), or empty string if no conditions
|
|
397
|
+
*
|
|
398
|
+
* @private
|
|
399
|
+
*/
|
|
400
|
+
private static buildSurrealWhereClause;
|
|
401
|
+
/**
|
|
402
|
+
* Builds the SELECT fields for SurrealQL queries.
|
|
403
|
+
*
|
|
404
|
+
* @description
|
|
405
|
+
* Generates the field list for the SELECT clause, resolving properties and collections
|
|
406
|
+
* via subqueries. Each property is fetched with a subquery that finds the link with the
|
|
407
|
+
* appropriate predicate and returns its target. Collections are similar but don't use LIMIT 1.
|
|
408
|
+
*
|
|
409
|
+
* Field types:
|
|
410
|
+
* - Properties: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X' LIMIT 1) AS propName`
|
|
411
|
+
* - Collections: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X') AS collName`
|
|
412
|
+
* - Author/Timestamp: Always included to provide metadata about each instance
|
|
413
|
+
*
|
|
414
|
+
* If properties or collections arrays are provided, only those fields are included.
|
|
415
|
+
* Otherwise, all properties/collections from metadata are included.
|
|
416
|
+
*
|
|
417
|
+
* @param metadata - Model metadata containing property and collection predicates
|
|
418
|
+
* @param properties - Optional array of property names to include (default: all)
|
|
419
|
+
* @param collections - Optional array of collection names to include (default: all)
|
|
420
|
+
* @returns Comma-separated SELECT field list
|
|
421
|
+
*
|
|
422
|
+
* @private
|
|
423
|
+
*/
|
|
424
|
+
private static buildSurrealSelectFields;
|
|
425
|
+
/**
|
|
426
|
+
* Builds the SELECT fields for SurrealQL queries using aggregation functions.
|
|
427
|
+
* Compatible with GROUP BY source queries.
|
|
428
|
+
*
|
|
429
|
+
* @private
|
|
430
|
+
*/
|
|
431
|
+
private static buildSurrealSelectFieldsWithAggregation;
|
|
432
|
+
/**
|
|
433
|
+
* Formats a value for use in SurrealQL queries.
|
|
434
|
+
*
|
|
435
|
+
* @description
|
|
436
|
+
* Handles different value types:
|
|
437
|
+
* - Strings: Wrapped in single quotes with backslash-escaped special characters
|
|
438
|
+
* - Numbers/booleans: Converted to string
|
|
439
|
+
* - Arrays: Recursively formatted and wrapped in brackets
|
|
440
|
+
*
|
|
441
|
+
* @param value - The value to format
|
|
442
|
+
* @returns Formatted value string ready for SurrealQL
|
|
443
|
+
*
|
|
444
|
+
* @private
|
|
445
|
+
*/
|
|
446
|
+
private static formatSurrealValue;
|
|
182
447
|
static instancesFromPrologResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query: Query, result: AllInstancesResult): Promise<ResultsWithTotalCount<T>>;
|
|
448
|
+
/**
|
|
449
|
+
* Converts SurrealDB query results to Ad4mModel instances.
|
|
450
|
+
*
|
|
451
|
+
* @param perspective - The perspective context
|
|
452
|
+
* @param query - The query parameters used
|
|
453
|
+
* @param result - Array of result objects from SurrealDB
|
|
454
|
+
* @returns Promise resolving to results with total count
|
|
455
|
+
*
|
|
456
|
+
* @internal
|
|
457
|
+
*/
|
|
458
|
+
static instancesFromSurrealResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query: Query, result: any[]): Promise<ResultsWithTotalCount<T>>;
|
|
459
|
+
/**
|
|
460
|
+
* Checks if a value matches a condition (for post-query filtering).
|
|
461
|
+
* @private
|
|
462
|
+
*/
|
|
463
|
+
private static matchesCondition;
|
|
183
464
|
/**
|
|
184
465
|
* Gets all instances of the model in the perspective that match the query params.
|
|
185
466
|
*
|
|
186
467
|
* @param perspective - The perspective to search in
|
|
187
468
|
* @param query - Optional query parameters to filter results
|
|
469
|
+
* @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
|
|
188
470
|
* @returns Array of matching models
|
|
189
471
|
*
|
|
190
472
|
* @example
|
|
191
473
|
* ```typescript
|
|
192
|
-
* // Get all recipes
|
|
474
|
+
* // Get all recipes (uses SurrealDB by default)
|
|
193
475
|
* const allRecipes = await Recipe.findAll(perspective);
|
|
194
476
|
*
|
|
195
|
-
* // Get recipes with specific criteria
|
|
477
|
+
* // Get recipes with specific criteria (uses SurrealDB)
|
|
196
478
|
* const recipes = await Recipe.findAll(perspective, {
|
|
197
479
|
* where: {
|
|
198
480
|
* name: "Pasta",
|
|
@@ -201,14 +483,18 @@ export declare class Ad4mModel {
|
|
|
201
483
|
* order: { createdAt: "DESC" },
|
|
202
484
|
* limit: 10
|
|
203
485
|
* });
|
|
486
|
+
*
|
|
487
|
+
* // Explicitly use Prolog (legacy, for backward compatibility)
|
|
488
|
+
* const recipesProlog = await Recipe.findAll(perspective, {}, false);
|
|
204
489
|
* ```
|
|
205
490
|
*/
|
|
206
|
-
static findAll<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query): Promise<T[]>;
|
|
491
|
+
static findAll<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, useSurrealDB?: boolean): Promise<T[]>;
|
|
207
492
|
/**
|
|
208
493
|
* Gets all instances with count of total matches without offset & limit applied.
|
|
209
494
|
*
|
|
210
495
|
* @param perspective - The perspective to search in
|
|
211
496
|
* @param query - Optional query parameters to filter results
|
|
497
|
+
* @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
|
|
212
498
|
* @returns Object containing results array and total count
|
|
213
499
|
*
|
|
214
500
|
* @example
|
|
@@ -218,9 +504,12 @@ export declare class Ad4mModel {
|
|
|
218
504
|
* limit: 10
|
|
219
505
|
* });
|
|
220
506
|
* console.log(`Showing 10 of ${totalCount} dessert recipes`);
|
|
507
|
+
*
|
|
508
|
+
* // Use Prolog explicitly (legacy)
|
|
509
|
+
* const { results, totalCount } = await Recipe.findAllAndCount(perspective, {}, false);
|
|
221
510
|
* ```
|
|
222
511
|
*/
|
|
223
|
-
static findAllAndCount<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query): Promise<ResultsWithTotalCount<T>>;
|
|
512
|
+
static findAllAndCount<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, useSurrealDB?: boolean): Promise<ResultsWithTotalCount<T>>;
|
|
224
513
|
/**
|
|
225
514
|
* Helper function for pagination with explicit page size and number.
|
|
226
515
|
*
|
|
@@ -228,6 +517,7 @@ export declare class Ad4mModel {
|
|
|
228
517
|
* @param pageSize - Number of items per page
|
|
229
518
|
* @param pageNumber - Which page to retrieve (1-based)
|
|
230
519
|
* @param query - Optional additional query parameters
|
|
520
|
+
* @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
|
|
231
521
|
* @returns Paginated results with metadata
|
|
232
522
|
*
|
|
233
523
|
* @example
|
|
@@ -236,15 +526,29 @@ export declare class Ad4mModel {
|
|
|
236
526
|
* where: { category: "Main Course" }
|
|
237
527
|
* });
|
|
238
528
|
* console.log(`Page ${page.pageNumber} of recipes, ${page.results.length} items`);
|
|
529
|
+
*
|
|
530
|
+
* // Use Prolog explicitly (legacy)
|
|
531
|
+
* const pageProlog = await Recipe.paginate(perspective, 10, 1, {}, false);
|
|
239
532
|
* ```
|
|
240
533
|
*/
|
|
241
|
-
static paginate<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?: Query): Promise<PaginationResult<T>>;
|
|
534
|
+
static paginate<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?: Query, useSurrealDB?: boolean): Promise<PaginationResult<T>>;
|
|
242
535
|
static countQueryToProlog(perspective: PerspectiveProxy, query?: Query, modelClassName?: string | null): Promise<string>;
|
|
536
|
+
/**
|
|
537
|
+
* Generates a SurrealQL COUNT query for the model.
|
|
538
|
+
*
|
|
539
|
+
* @param perspective - The perspective context
|
|
540
|
+
* @param query - Query parameters to filter the count
|
|
541
|
+
* @returns SurrealQL COUNT query string
|
|
542
|
+
*
|
|
543
|
+
* @private
|
|
544
|
+
*/
|
|
545
|
+
static countQueryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string>;
|
|
243
546
|
/**
|
|
244
547
|
* Gets a count of all matching instances.
|
|
245
548
|
*
|
|
246
549
|
* @param perspective - The perspective to search in
|
|
247
550
|
* @param query - Optional query parameters to filter results
|
|
551
|
+
* @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
|
|
248
552
|
* @returns Total count of matching entities
|
|
249
553
|
*
|
|
250
554
|
* @example
|
|
@@ -253,9 +557,12 @@ export declare class Ad4mModel {
|
|
|
253
557
|
* const activeRecipes = await Recipe.count(perspective, {
|
|
254
558
|
* where: { status: "active" }
|
|
255
559
|
* });
|
|
560
|
+
*
|
|
561
|
+
* // Use Prolog explicitly (legacy)
|
|
562
|
+
* const countProlog = await Recipe.count(perspective, {}, false);
|
|
256
563
|
* ```
|
|
257
564
|
*/
|
|
258
|
-
static count(perspective: PerspectiveProxy, query?: Query):
|
|
565
|
+
static count(perspective: PerspectiveProxy, query?: Query, useSurrealDB?: boolean): any;
|
|
259
566
|
private setProperty;
|
|
260
567
|
private setCollectionSetter;
|
|
261
568
|
private setCollectionAdder;
|
|
@@ -359,6 +666,74 @@ export declare class Ad4mModel {
|
|
|
359
666
|
* ```
|
|
360
667
|
*/
|
|
361
668
|
static query<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query): ModelQueryBuilder<T>;
|
|
669
|
+
/**
|
|
670
|
+
* Creates an Ad4mModel class from a JSON Schema definition.
|
|
671
|
+
*
|
|
672
|
+
* @description
|
|
673
|
+
* This method dynamically generates an Ad4mModel subclass from a JSON Schema,
|
|
674
|
+
* enabling integration with systems that use JSON Schema for type definitions.
|
|
675
|
+
*
|
|
676
|
+
* The method follows a cascading approach for determining predicates:
|
|
677
|
+
* 1. Explicit configuration in options parameter (highest precedence)
|
|
678
|
+
* 2. x-ad4m metadata in the JSON Schema
|
|
679
|
+
* 3. Inference from schema title and property names
|
|
680
|
+
* 4. Error if no namespace can be determined
|
|
681
|
+
*
|
|
682
|
+
* @example
|
|
683
|
+
* ```typescript
|
|
684
|
+
* // With explicit configuration
|
|
685
|
+
* const PersonClass = Ad4mModel.fromJSONSchema(schema, {
|
|
686
|
+
* name: "Person",
|
|
687
|
+
* namespace: "person://",
|
|
688
|
+
* resolveLanguage: "literal"
|
|
689
|
+
* });
|
|
690
|
+
*
|
|
691
|
+
* // With property mapping
|
|
692
|
+
* const ContactClass = Ad4mModel.fromJSONSchema(schema, {
|
|
693
|
+
* name: "Contact",
|
|
694
|
+
* namespace: "contact://",
|
|
695
|
+
* propertyMapping: {
|
|
696
|
+
* "name": "foaf://name",
|
|
697
|
+
* "email": "foaf://mbox"
|
|
698
|
+
* }
|
|
699
|
+
* });
|
|
700
|
+
*
|
|
701
|
+
* // With x-ad4m metadata in schema
|
|
702
|
+
* const schema = {
|
|
703
|
+
* "title": "Product",
|
|
704
|
+
* "x-ad4m": { "namespace": "product://" },
|
|
705
|
+
* "properties": {
|
|
706
|
+
* "name": {
|
|
707
|
+
* "type": "string",
|
|
708
|
+
* "x-ad4m": { "through": "product://title" }
|
|
709
|
+
* }
|
|
710
|
+
* }
|
|
711
|
+
* };
|
|
712
|
+
* const ProductClass = Ad4mModel.fromJSONSchema(schema, { name: "Product" });
|
|
713
|
+
* ```
|
|
714
|
+
*
|
|
715
|
+
* @param schema - JSON Schema definition
|
|
716
|
+
* @param options - Configuration options
|
|
717
|
+
* @returns Generated Ad4mModel subclass
|
|
718
|
+
* @throws Error when namespace cannot be inferred
|
|
719
|
+
*/
|
|
720
|
+
static fromJSONSchema(schema: JSONSchema, options: JSONSchemaToModelOptions): typeof Ad4mModel;
|
|
721
|
+
/**
|
|
722
|
+
* Determines the namespace for predicates using cascading precedence
|
|
723
|
+
*/
|
|
724
|
+
private static determineNamespace;
|
|
725
|
+
/**
|
|
726
|
+
* Determines the predicate for a specific property using cascading precedence
|
|
727
|
+
*/
|
|
728
|
+
private static determinePredicate;
|
|
729
|
+
/**
|
|
730
|
+
* Gets property-specific options using cascading precedence
|
|
731
|
+
*/
|
|
732
|
+
private static getPropertyOption;
|
|
733
|
+
/**
|
|
734
|
+
* Gets default value for a JSON Schema type
|
|
735
|
+
*/
|
|
736
|
+
private static getDefaultValueForType;
|
|
362
737
|
}
|
|
363
738
|
/** Query builder for Ad4mModel queries.
|
|
364
739
|
* Allows building queries with a fluent interface and either running them once
|
|
@@ -386,6 +761,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
386
761
|
private modelClassName;
|
|
387
762
|
private ctor;
|
|
388
763
|
private currentSubscription?;
|
|
764
|
+
private useSurrealDBFlag;
|
|
389
765
|
constructor(perspective: PerspectiveProxy, ctor: typeof Ad4mModel, query?: Query);
|
|
390
766
|
/**
|
|
391
767
|
* Disposes of the current subscription if one exists.
|
|
@@ -490,6 +866,32 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
490
866
|
*/
|
|
491
867
|
collections(collections: string[]): ModelQueryBuilder<T>;
|
|
492
868
|
overrideModelClassName(className: string): ModelQueryBuilder<T>;
|
|
869
|
+
/**
|
|
870
|
+
* Enables or disables SurrealDB query path.
|
|
871
|
+
*
|
|
872
|
+
* @param enabled - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
|
|
873
|
+
* @returns The query builder for chaining
|
|
874
|
+
*
|
|
875
|
+
* @example
|
|
876
|
+
* ```typescript
|
|
877
|
+
* // Use SurrealDB (default)
|
|
878
|
+
* const recipes = await Recipe.query(perspective)
|
|
879
|
+
* .where({ category: "Dessert" })
|
|
880
|
+
* .useSurrealDB(true)
|
|
881
|
+
* .get();
|
|
882
|
+
*
|
|
883
|
+
* // Use Prolog (legacy)
|
|
884
|
+
* const recipesProlog = await Recipe.query(perspective)
|
|
885
|
+
* .where({ category: "Dessert" })
|
|
886
|
+
* .useSurrealDB(false)
|
|
887
|
+
* .get();
|
|
888
|
+
* ```
|
|
889
|
+
*
|
|
890
|
+
* @remarks
|
|
891
|
+
* Note: Subscriptions (subscribe(), countSubscribe(), paginateSubscribe()) default to SurrealDB live queries
|
|
892
|
+
* if useSurrealDB(true) is set (default).
|
|
893
|
+
*/
|
|
894
|
+
useSurrealDB(enabled?: boolean): ModelQueryBuilder<T>;
|
|
493
895
|
/**
|
|
494
896
|
* Executes the query once and returns the results.
|
|
495
897
|
*
|
|
@@ -507,7 +909,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
507
909
|
* Subscribes to the query and receives updates when results change.
|
|
508
910
|
*
|
|
509
911
|
* This method:
|
|
510
|
-
* 1. Creates and initializes a
|
|
912
|
+
* 1. Creates and initializes a SurrealDB live query subscription (default)
|
|
511
913
|
* 2. Sets up the callback to process future updates
|
|
512
914
|
* 3. Returns the initial results immediately
|
|
513
915
|
*
|
|
@@ -529,6 +931,10 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
529
931
|
* // When done with subscription:
|
|
530
932
|
* builder.dispose();
|
|
531
933
|
* ```
|
|
934
|
+
*
|
|
935
|
+
* @remarks
|
|
936
|
+
* By default, this uses SurrealDB live queries for real-time updates.
|
|
937
|
+
* Prolog subscriptions remain available via `.useSurrealDB(false)`.
|
|
532
938
|
*/
|
|
533
939
|
subscribe(callback: (results: T[]) => void): Promise<T[]>;
|
|
534
940
|
/**
|
|
@@ -548,7 +954,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
548
954
|
* Subscribes to count updates for matching entities.
|
|
549
955
|
*
|
|
550
956
|
* This method:
|
|
551
|
-
* 1. Creates and initializes a
|
|
957
|
+
* 1. Creates and initializes a SurrealDB live query subscription for the count (default)
|
|
552
958
|
* 2. Sets up the callback to process future count updates
|
|
553
959
|
* 3. Returns the initial count immediately
|
|
554
960
|
*
|
|
@@ -570,6 +976,10 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
570
976
|
* // When done with subscription:
|
|
571
977
|
* builder.dispose();
|
|
572
978
|
* ```
|
|
979
|
+
*
|
|
980
|
+
* @remarks
|
|
981
|
+
* By default, this uses SurrealDB live queries for real-time updates.
|
|
982
|
+
* Prolog subscriptions remain available via `.useSurrealDB(false)`.
|
|
573
983
|
*/
|
|
574
984
|
countSubscribe(callback: (count: number) => void): Promise<number>;
|
|
575
985
|
/**
|
|
@@ -592,7 +1002,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
592
1002
|
* Subscribes to paginated results updates.
|
|
593
1003
|
*
|
|
594
1004
|
* This method:
|
|
595
|
-
* 1. Creates and initializes a
|
|
1005
|
+
* 1. Creates and initializes a SurrealDB live query subscription for the paginated results (default)
|
|
596
1006
|
* 2. Sets up the callback to process future page updates
|
|
597
1007
|
* 3. Returns the initial page immediately
|
|
598
1008
|
*
|
|
@@ -616,6 +1026,10 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
616
1026
|
* // When done with subscription:
|
|
617
1027
|
* builder.dispose();
|
|
618
1028
|
* ```
|
|
1029
|
+
*
|
|
1030
|
+
* @remarks
|
|
1031
|
+
* By default, this uses SurrealDB live queries for real-time updates.
|
|
1032
|
+
* Prolog subscriptions remain available via `.useSurrealDB(false)`.
|
|
619
1033
|
*/
|
|
620
1034
|
paginateSubscribe(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
|
|
621
1035
|
}
|