@coasys/ad4m 0.10.0 → 0.10.1-dev-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/lib/index.cjs +3785 -843
  2. package/lib/index.js +3777 -839
  3. package/lib/src/Ad4mClient.js +2 -1
  4. package/lib/src/Literal.js +4 -1
  5. package/lib/src/ai/AIClient.d.ts +8 -2
  6. package/lib/src/ai/AIClient.js +25 -14
  7. package/lib/src/ai/AIResolver.d.ts +25 -6
  8. package/lib/src/ai/AIResolver.js +102 -18
  9. package/lib/src/index.d.ts +4 -3
  10. package/lib/src/index.js +4 -3
  11. package/lib/src/model/Ad4mModel.d.ts +730 -0
  12. package/lib/src/model/Ad4mModel.js +1399 -0
  13. package/lib/src/{subject → model}/Subject.d.ts +2 -2
  14. package/lib/src/{subject → model}/Subject.js +18 -18
  15. package/lib/src/model/decorators.d.ts +502 -0
  16. package/lib/src/model/decorators.js +683 -0
  17. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +2 -2
  18. package/lib/src/neighbourhood/NeighbourhoodClient.js +13 -10
  19. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -2
  20. package/lib/src/neighbourhood/NeighbourhoodProxy.js +4 -4
  21. package/lib/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  22. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +73 -0
  23. package/lib/src/neighbourhood/NeighbourhoodResolver.d.ts +2 -2
  24. package/lib/src/neighbourhood/NeighbourhoodResolver.js +6 -4
  25. package/lib/src/perspectives/PerspectiveClient.d.ts +23 -11
  26. package/lib/src/perspectives/PerspectiveClient.js +147 -51
  27. package/lib/src/perspectives/PerspectiveProxy.d.ts +494 -54
  28. package/lib/src/perspectives/PerspectiveProxy.js +684 -67
  29. package/lib/src/perspectives/PerspectiveResolver.d.ts +24 -9
  30. package/lib/src/perspectives/PerspectiveResolver.js +151 -46
  31. package/lib/src/runtime/RuntimeClient.d.ts +8 -2
  32. package/lib/src/runtime/RuntimeClient.js +64 -0
  33. package/lib/src/runtime/RuntimeResolver.d.ts +27 -1
  34. package/lib/src/runtime/RuntimeResolver.js +138 -0
  35. package/lib/src/schema.gql +55 -16
  36. package/lib/src/typeDefs.js +55 -16
  37. package/package.json +4 -3
  38. package/src/Ad4mClient.test.ts +51 -19
  39. package/src/Ad4mClient.ts +3 -1
  40. package/src/Literal.ts +4 -1
  41. package/src/ai/AIClient.ts +35 -14
  42. package/src/ai/AIResolver.ts +78 -16
  43. package/src/index.ts +4 -3
  44. package/src/model/Ad4mModel.ts +1651 -0
  45. package/src/{subject → model}/Subject.ts +16 -16
  46. package/src/{subject/SDNADecorators.ts → model/decorators.ts} +384 -50
  47. package/src/neighbourhood/NeighbourhoodClient.ts +13 -10
  48. package/src/neighbourhood/NeighbourhoodProxy.test.ts +100 -0
  49. package/src/neighbourhood/NeighbourhoodProxy.ts +4 -4
  50. package/src/neighbourhood/NeighbourhoodResolver.ts +2 -2
  51. package/src/perspectives/PerspectiveClient.ts +156 -51
  52. package/src/perspectives/PerspectiveProxy.ts +766 -82
  53. package/src/perspectives/PerspectiveResolver.ts +134 -23
  54. package/src/runtime/RuntimeClient.ts +71 -2
  55. package/src/runtime/RuntimeResolver.ts +91 -1
  56. package/lib/src/subject/SDNADecorators.d.ts +0 -188
  57. package/lib/src/subject/SDNADecorators.js +0 -360
  58. package/lib/src/subject/SubjectEntity.d.ts +0 -102
  59. package/lib/src/subject/SubjectEntity.js +0 -267
  60. package/src/subject/SubjectEntity.ts +0 -315
  61. package/yarn-error.log +0 -90
  62. /package/lib/src/{subject → model}/util.d.ts +0 -0
  63. /package/lib/src/{subject → model}/util.js +0 -0
  64. /package/src/{subject → model}/util.ts +0 -0
@@ -0,0 +1,730 @@
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
+ }
42
+ type ValueTuple = [name: string, value: any, resolve?: boolean];
43
+ type WhereOps = {
44
+ not: string | number | boolean | string[] | number[];
45
+ between: [number, number];
46
+ lt: number;
47
+ lte: number;
48
+ gt: number;
49
+ gte: number;
50
+ };
51
+ type WhereCondition = string | number | boolean | string[] | number[] | {
52
+ [K in keyof WhereOps]?: WhereOps[K];
53
+ };
54
+ type Where = {
55
+ [propertyName: string]: WhereCondition;
56
+ };
57
+ type Order = {
58
+ [propertyName: string]: "ASC" | "DESC";
59
+ };
60
+ export type Query = {
61
+ source?: string;
62
+ properties?: string[];
63
+ collections?: string[];
64
+ where?: Where;
65
+ order?: Order;
66
+ offset?: number;
67
+ limit?: number;
68
+ count?: boolean;
69
+ };
70
+ export type AllInstancesResult = {
71
+ AllInstances: Ad4mModel[];
72
+ TotalCount?: number;
73
+ isInit?: boolean;
74
+ };
75
+ export type ResultsWithTotalCount<T> = {
76
+ results: T[];
77
+ totalCount?: number;
78
+ };
79
+ export type PaginationResult<T> = {
80
+ results: T[];
81
+ totalCount?: number;
82
+ pageSize: number;
83
+ pageNumber: number;
84
+ };
85
+ /**
86
+ * Base class for defining data models in AD4M.
87
+ *
88
+ * @description
89
+ * Ad4mModel provides the foundation for creating data models that are stored in AD4M perspectives.
90
+ * Each model instance is represented as a subgraph in the perspective, with properties and collections
91
+ * mapped to links in that graph. The class uses Prolog-based queries to efficiently search and filter
92
+ * instances based on their properties and relationships.
93
+ *
94
+ * Key concepts:
95
+ * - Each model instance has a unique base expression that serves as its identifier
96
+ * - Properties are stored as links with predicates defined by the `through` option
97
+ * - Collections represent one-to-many relationships as sets of links
98
+ * - Queries are translated to Prolog for efficient graph pattern matching
99
+ * - Changes are tracked through the perspective's subscription system
100
+ *
101
+ * @example
102
+ * ```typescript
103
+ * // Define a recipe model
104
+ * @ModelOptions({ name: "Recipe" })
105
+ * class Recipe extends Ad4mModel {
106
+ * // Required property with literal value
107
+ * @Property({
108
+ * through: "recipe://name",
109
+ * resolveLanguage: "literal"
110
+ * })
111
+ * name: string = "";
112
+ *
113
+ * // Optional property with custom initial value
114
+ * @Optional({
115
+ * through: "recipe://status",
116
+ * initial: "recipe://draft"
117
+ * })
118
+ * status: string = "";
119
+ *
120
+ * // Read-only computed property
121
+ * @ReadOnly({
122
+ * through: "recipe://rating",
123
+ * getter: `
124
+ * findall(Rating, triple(Base, "recipe://user_rating", Rating), Ratings),
125
+ * sum_list(Ratings, Sum),
126
+ * length(Ratings, Count),
127
+ * Value is Sum / Count
128
+ * `
129
+ * })
130
+ * averageRating: number = 0;
131
+ *
132
+ * // Collection of ingredients
133
+ * @Collection({ through: "recipe://ingredient" })
134
+ * ingredients: string[] = [];
135
+ *
136
+ * // Collection of comments that are instances of another model
137
+ * @Collection({
138
+ * through: "recipe://comment",
139
+ * where: { isInstance: Comment }
140
+ * })
141
+ * comments: Comment[] = [];
142
+ * }
143
+ *
144
+ * // Create and save a new recipe
145
+ * const recipe = new Recipe(perspective);
146
+ * recipe.name = "Chocolate Cake";
147
+ * recipe.ingredients = ["flour", "sugar", "cocoa"];
148
+ * await recipe.save();
149
+ *
150
+ * // Query recipes in different ways
151
+ * // Get all recipes
152
+ * const allRecipes = await Recipe.findAll(perspective);
153
+ *
154
+ * // Find recipes with specific criteria
155
+ * const desserts = await Recipe.findAll(perspective, {
156
+ * where: {
157
+ * status: "recipe://published",
158
+ * averageRating: { gt: 4 }
159
+ * },
160
+ * order: { name: "ASC" },
161
+ * limit: 10
162
+ * });
163
+ *
164
+ * // Use the fluent query builder
165
+ * const popularRecipes = await Recipe.query(perspective)
166
+ * .where({ averageRating: { gt: 4.5 } })
167
+ * .order({ averageRating: "DESC" })
168
+ * .limit(5)
169
+ * .get();
170
+ *
171
+ * // Subscribe to real-time updates
172
+ * await Recipe.query(perspective)
173
+ * .where({ status: "recipe://cooking" })
174
+ * .subscribe(recipes => {
175
+ * console.log("Currently being cooked:", recipes);
176
+ * });
177
+ *
178
+ * // Paginate results
179
+ * const { results, totalCount, pageNumber } = await Recipe.query(perspective)
180
+ * .where({ status: "recipe://published" })
181
+ * .paginate(10, 1);
182
+ * ```
183
+ */
184
+ export declare class Ad4mModel {
185
+ #private;
186
+ author: string;
187
+ timestamp: string;
188
+ private static classNamesByClass;
189
+ static getClassName(perspective: PerspectiveProxy): Promise<string>;
190
+ /**
191
+ * Constructs a new model instance.
192
+ *
193
+ * @param perspective - The perspective where this model will be stored
194
+ * @param baseExpression - Optional unique identifier for this instance
195
+ * @param source - Optional source expression this instance is linked to
196
+ *
197
+ * @example
198
+ * ```typescript
199
+ * // Create a new recipe with auto-generated base expression
200
+ * const recipe = new Recipe(perspective);
201
+ *
202
+ * // Create with specific base expression
203
+ * const recipe = new Recipe(perspective, "recipe://chocolate-cake");
204
+ *
205
+ * // Create with source link
206
+ * const recipe = new Recipe(perspective, undefined, "cookbook://desserts");
207
+ * ```
208
+ */
209
+ constructor(perspective: PerspectiveProxy, baseExpression?: string, source?: string);
210
+ /**
211
+ * Gets the base expression of the subject.
212
+ */
213
+ get baseExpression(): string;
214
+ /**
215
+ * Protected getter for the perspective.
216
+ * Allows subclasses to access the perspective while keeping it private from external code.
217
+ */
218
+ protected get perspective(): PerspectiveProxy;
219
+ static assignValuesToInstance(perspective: PerspectiveProxy, instance: Ad4mModel, values: ValueTuple[]): Promise<void>;
220
+ private getData;
221
+ static queryToProlog(perspective: PerspectiveProxy, query: Query, modelClassName?: string | null): Promise<string>;
222
+ static instancesFromPrologResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query: Query, result: AllInstancesResult): Promise<ResultsWithTotalCount<T>>;
223
+ /**
224
+ * Gets all instances of the model in the perspective that match the query params.
225
+ *
226
+ * @param perspective - The perspective to search in
227
+ * @param query - Optional query parameters to filter results
228
+ * @returns Array of matching models
229
+ *
230
+ * @example
231
+ * ```typescript
232
+ * // Get all recipes
233
+ * const allRecipes = await Recipe.findAll(perspective);
234
+ *
235
+ * // Get recipes with specific criteria
236
+ * const recipes = await Recipe.findAll(perspective, {
237
+ * where: {
238
+ * name: "Pasta",
239
+ * rating: { gt: 4 }
240
+ * },
241
+ * order: { createdAt: "DESC" },
242
+ * limit: 10
243
+ * });
244
+ * ```
245
+ */
246
+ static findAll<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query): Promise<T[]>;
247
+ /**
248
+ * Gets all instances with count of total matches without offset & limit applied.
249
+ *
250
+ * @param perspective - The perspective to search in
251
+ * @param query - Optional query parameters to filter results
252
+ * @returns Object containing results array and total count
253
+ *
254
+ * @example
255
+ * ```typescript
256
+ * const { results, totalCount } = await Recipe.findAllAndCount(perspective, {
257
+ * where: { category: "Dessert" },
258
+ * limit: 10
259
+ * });
260
+ * console.log(`Showing 10 of ${totalCount} dessert recipes`);
261
+ * ```
262
+ */
263
+ static findAllAndCount<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query): Promise<ResultsWithTotalCount<T>>;
264
+ /**
265
+ * Helper function for pagination with explicit page size and number.
266
+ *
267
+ * @param perspective - The perspective to search in
268
+ * @param pageSize - Number of items per page
269
+ * @param pageNumber - Which page to retrieve (1-based)
270
+ * @param query - Optional additional query parameters
271
+ * @returns Paginated results with metadata
272
+ *
273
+ * @example
274
+ * ```typescript
275
+ * const page = await Recipe.paginate(perspective, 10, 1, {
276
+ * where: { category: "Main Course" }
277
+ * });
278
+ * console.log(`Page ${page.pageNumber} of recipes, ${page.results.length} items`);
279
+ * ```
280
+ */
281
+ static paginate<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?: Query): Promise<PaginationResult<T>>;
282
+ static countQueryToProlog(perspective: PerspectiveProxy, query?: Query, modelClassName?: string | null): Promise<string>;
283
+ /**
284
+ * Gets a count of all matching instances.
285
+ *
286
+ * @param perspective - The perspective to search in
287
+ * @param query - Optional query parameters to filter results
288
+ * @returns Total count of matching entities
289
+ *
290
+ * @example
291
+ * ```typescript
292
+ * const totalRecipes = await Recipe.count(perspective);
293
+ * const activeRecipes = await Recipe.count(perspective, {
294
+ * where: { status: "active" }
295
+ * });
296
+ * ```
297
+ */
298
+ static count(perspective: PerspectiveProxy, query?: Query): Promise<any>;
299
+ private setProperty;
300
+ private setCollectionSetter;
301
+ private setCollectionAdder;
302
+ private setCollectionRemover;
303
+ /**
304
+ * Saves the model instance to the perspective.
305
+ * Creates a new instance with the base expression and links it to the source.
306
+ *
307
+ * @param batchId - Optional batch ID for batch operations
308
+ * @throws Will throw if instance creation, linking, or updating fails
309
+ *
310
+ * @example
311
+ * ```typescript
312
+ * const recipe = new Recipe(perspective);
313
+ * recipe.name = "Spaghetti";
314
+ * recipe.ingredients = ["pasta", "tomato sauce"];
315
+ * await recipe.save();
316
+ *
317
+ * // Or with batch operations:
318
+ * const batchId = await perspective.createBatch();
319
+ * await recipe.save(batchId);
320
+ * await perspective.commitBatch(batchId);
321
+ * ```
322
+ */
323
+ save(batchId?: string): Promise<void>;
324
+ private cleanCopy;
325
+ private innerUpdate;
326
+ /**
327
+ * Updates the model instance's properties and collections.
328
+ *
329
+ * @param batchId - Optional batch ID for batch operations
330
+ * @throws Will throw if property setting or collection updates fail
331
+ *
332
+ * @example
333
+ * ```typescript
334
+ * const recipe = await Recipe.findAll(perspective)[0];
335
+ * recipe.rating = 5;
336
+ * recipe.ingredients.push("garlic");
337
+ * await recipe.update();
338
+ *
339
+ * // Or with batch operations:
340
+ * const batchId = await perspective.createBatch();
341
+ * await recipe.update(batchId);
342
+ * await perspective.commitBatch(batchId);
343
+ * ```
344
+ */
345
+ update(batchId?: string): Promise<void>;
346
+ /**
347
+ * Gets the model instance with all properties and collections populated.
348
+ *
349
+ * @returns The populated model instance
350
+ * @throws Will throw if data retrieval fails
351
+ *
352
+ * @example
353
+ * ```typescript
354
+ * const recipe = new Recipe(perspective, existingId);
355
+ * await recipe.get();
356
+ * console.log(recipe.name, recipe.ingredients);
357
+ * ```
358
+ */
359
+ get(): Promise<this>;
360
+ /**
361
+ * Deletes the model instance from the perspective.
362
+ *
363
+ * @param batchId - Optional batch ID for batch operations
364
+ * @throws Will throw if removal fails
365
+ *
366
+ * @example
367
+ * ```typescript
368
+ * const recipe = await Recipe.findAll(perspective)[0];
369
+ * await recipe.delete();
370
+ *
371
+ * // Or with batch operations:
372
+ * const batchId = await perspective.createBatch();
373
+ * await recipe.delete(batchId);
374
+ * await perspective.commitBatch(batchId);
375
+ * ```
376
+ */
377
+ delete(batchId?: string): Promise<void>;
378
+ /**
379
+ * Creates a query builder for fluent query construction.
380
+ *
381
+ * @param perspective - The perspective to query
382
+ * @param query - Optional initial query parameters
383
+ * @returns A new query builder instance
384
+ *
385
+ * @example
386
+ * ```typescript
387
+ * const recipes = await Recipe.query(perspective)
388
+ * .where({ category: "Dessert" })
389
+ * .order({ rating: "DESC" })
390
+ * .limit(5)
391
+ * .run();
392
+ *
393
+ * // With real-time updates
394
+ * await Recipe.query(perspective)
395
+ * .where({ status: "cooking" })
396
+ * .subscribe(recipes => {
397
+ * console.log("Currently cooking:", recipes);
398
+ * });
399
+ * ```
400
+ */
401
+ static query<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query): ModelQueryBuilder<T>;
402
+ /**
403
+ * Creates an Ad4mModel class from a JSON Schema definition.
404
+ *
405
+ * @description
406
+ * This method dynamically generates an Ad4mModel subclass from a JSON Schema,
407
+ * enabling integration with systems that use JSON Schema for type definitions.
408
+ *
409
+ * The method follows a cascading approach for determining predicates:
410
+ * 1. Explicit configuration in options parameter (highest precedence)
411
+ * 2. x-ad4m metadata in the JSON Schema
412
+ * 3. Inference from schema title and property names
413
+ * 4. Error if no namespace can be determined
414
+ *
415
+ * @example
416
+ * ```typescript
417
+ * // With explicit configuration
418
+ * const PersonClass = Ad4mModel.fromJSONSchema(schema, {
419
+ * name: "Person",
420
+ * namespace: "person://",
421
+ * resolveLanguage: "literal"
422
+ * });
423
+ *
424
+ * // With property mapping
425
+ * const ContactClass = Ad4mModel.fromJSONSchema(schema, {
426
+ * name: "Contact",
427
+ * namespace: "contact://",
428
+ * propertyMapping: {
429
+ * "name": "foaf://name",
430
+ * "email": "foaf://mbox"
431
+ * }
432
+ * });
433
+ *
434
+ * // With x-ad4m metadata in schema
435
+ * const schema = {
436
+ * "title": "Product",
437
+ * "x-ad4m": { "namespace": "product://" },
438
+ * "properties": {
439
+ * "name": {
440
+ * "type": "string",
441
+ * "x-ad4m": { "through": "product://title" }
442
+ * }
443
+ * }
444
+ * };
445
+ * const ProductClass = Ad4mModel.fromJSONSchema(schema, { name: "Product" });
446
+ * ```
447
+ *
448
+ * @param schema - JSON Schema definition
449
+ * @param options - Configuration options
450
+ * @returns Generated Ad4mModel subclass
451
+ * @throws Error when namespace cannot be inferred
452
+ */
453
+ static fromJSONSchema(schema: JSONSchema, options: JSONSchemaToModelOptions): typeof Ad4mModel;
454
+ /**
455
+ * Determines the namespace for predicates using cascading precedence
456
+ */
457
+ private static determineNamespace;
458
+ /**
459
+ * Determines the predicate for a specific property using cascading precedence
460
+ */
461
+ private static determinePredicate;
462
+ /**
463
+ * Gets property-specific options using cascading precedence
464
+ */
465
+ private static getPropertyOption;
466
+ /**
467
+ * Gets default value for a JSON Schema type
468
+ */
469
+ private static getDefaultValueForType;
470
+ }
471
+ /** Query builder for Ad4mModel queries.
472
+ * Allows building queries with a fluent interface and either running them once
473
+ * or subscribing to updates.
474
+ *
475
+ * @example
476
+ * ```typescript
477
+ * const builder = Recipe.query(perspective)
478
+ * .where({ category: "Dessert" })
479
+ * .order({ rating: "DESC" })
480
+ * .limit(10);
481
+ *
482
+ * // Run once
483
+ * const recipes = await builder.run();
484
+ *
485
+ * // Or subscribe to updates
486
+ * await builder.subscribe(recipes => {
487
+ * console.log("Updated recipes:", recipes);
488
+ * });
489
+ * ```
490
+ */
491
+ export declare class ModelQueryBuilder<T extends Ad4mModel> {
492
+ private perspective;
493
+ private queryParams;
494
+ private modelClassName;
495
+ private ctor;
496
+ private currentSubscription?;
497
+ constructor(perspective: PerspectiveProxy, ctor: typeof Ad4mModel, query?: Query);
498
+ /**
499
+ * Disposes of the current subscription if one exists.
500
+ *
501
+ * This method:
502
+ * 1. Stops the keepalive signals to the subscription
503
+ * 2. Unsubscribes from GraphQL subscription updates
504
+ * 3. Notifies the backend to clean up subscription resources
505
+ * 4. Clears the subscription reference
506
+ *
507
+ * You should call this method when you're done with a subscription
508
+ * to prevent memory leaks and ensure proper cleanup.
509
+ */
510
+ dispose(): void;
511
+ /**
512
+ * Adds where conditions to the query.
513
+ *
514
+ * @param conditions - The conditions to filter by
515
+ * @returns The query builder for chaining
516
+ *
517
+ * @example
518
+ * ```typescript
519
+ * .where({
520
+ * category: "Dessert",
521
+ * rating: { gt: 4 },
522
+ * tags: ["vegan", "quick"],
523
+ * published: true
524
+ * })
525
+ * ```
526
+ */
527
+ where(conditions: Where): ModelQueryBuilder<T>;
528
+ /**
529
+ * Sets the order for the query results.
530
+ *
531
+ * @param orderBy - The ordering criteria
532
+ * @returns The query builder for chaining
533
+ *
534
+ * @example
535
+ * ```typescript
536
+ * .order({ createdAt: "DESC" })
537
+ * ```
538
+ */
539
+ order(orderBy: Order): ModelQueryBuilder<T>;
540
+ /**
541
+ * Sets the maximum number of results to return.
542
+ *
543
+ * @param limit - Maximum number of results
544
+ * @returns The query builder for chaining
545
+ *
546
+ * @example
547
+ * ```typescript
548
+ * .limit(10)
549
+ * ```
550
+ */
551
+ limit(limit: number): ModelQueryBuilder<T>;
552
+ /**
553
+ * Sets the number of results to skip.
554
+ *
555
+ * @param offset - Number of results to skip
556
+ * @returns The query builder for chaining
557
+ *
558
+ * @example
559
+ * ```typescript
560
+ * .offset(20) // Skip first 20 results
561
+ * ```
562
+ */
563
+ offset(offset: number): ModelQueryBuilder<T>;
564
+ /**
565
+ * Sets the source filter for the query.
566
+ *
567
+ * @param source - The source to filter by
568
+ * @returns The query builder for chaining
569
+ *
570
+ * @example
571
+ * ```typescript
572
+ * .source("ad4m://self")
573
+ * ```
574
+ */
575
+ source(source: string): ModelQueryBuilder<T>;
576
+ /**
577
+ * Specifies which properties to include in the results.
578
+ *
579
+ * @param properties - Array of property names to include
580
+ * @returns The query builder for chaining
581
+ *
582
+ * @example
583
+ * ```typescript
584
+ * .properties(["name", "description", "rating"])
585
+ * ```
586
+ */
587
+ properties(properties: string[]): ModelQueryBuilder<T>;
588
+ /**
589
+ * Specifies which collections to include in the results.
590
+ *
591
+ * @param collections - Array of collection names to include
592
+ * @returns The query builder for chaining
593
+ *
594
+ * @example
595
+ * ```typescript
596
+ * .collections(["ingredients", "steps"])
597
+ * ```
598
+ */
599
+ collections(collections: string[]): ModelQueryBuilder<T>;
600
+ overrideModelClassName(className: string): ModelQueryBuilder<T>;
601
+ /**
602
+ * Executes the query once and returns the results.
603
+ *
604
+ * @returns Array of matching entities
605
+ *
606
+ * @example
607
+ * ```typescript
608
+ * const recipes = await Recipe.query(perspective)
609
+ * .where({ category: "Dessert" })
610
+ * .get();
611
+ * ```
612
+ */
613
+ get(): Promise<T[]>;
614
+ /**
615
+ * Subscribes to the query and receives updates when results change.
616
+ *
617
+ * This method:
618
+ * 1. Creates and initializes a Prolog query subscription
619
+ * 2. Sets up the callback to process future updates
620
+ * 3. Returns the initial results immediately
621
+ *
622
+ * Remember to call dispose() when you're done with the subscription
623
+ * to clean up resources.
624
+ *
625
+ * @param callback - Function to call with updated results
626
+ * @returns Initial results array
627
+ *
628
+ * @example
629
+ * ```typescript
630
+ * const builder = Recipe.query(perspective)
631
+ * .where({ status: "cooking" });
632
+ *
633
+ * const initialRecipes = await builder.subscribe(recipes => {
634
+ * console.log("Updated recipes:", recipes);
635
+ * });
636
+ *
637
+ * // When done with subscription:
638
+ * builder.dispose();
639
+ * ```
640
+ */
641
+ subscribe(callback: (results: T[]) => void): Promise<T[]>;
642
+ /**
643
+ * Gets the total count of matching entities.
644
+ *
645
+ * @returns Total count
646
+ *
647
+ * @example
648
+ * ```typescript
649
+ * const totalDesserts = await Recipe.query(perspective)
650
+ * .where({ category: "Dessert" })
651
+ * .count();
652
+ * ```
653
+ */
654
+ count(): Promise<number>;
655
+ /**
656
+ * Subscribes to count updates for matching entities.
657
+ *
658
+ * This method:
659
+ * 1. Creates and initializes a Prolog query subscription for the count
660
+ * 2. Sets up the callback to process future count updates
661
+ * 3. Returns the initial count immediately
662
+ *
663
+ * Remember to call dispose() when you're done with the subscription
664
+ * to clean up resources.
665
+ *
666
+ * @param callback - Function to call with updated count
667
+ * @returns Initial count
668
+ *
669
+ * @example
670
+ * ```typescript
671
+ * const builder = Recipe.query(perspective)
672
+ * .where({ status: "active" });
673
+ *
674
+ * const initialCount = await builder.countSubscribe(count => {
675
+ * console.log("Active items:", count);
676
+ * });
677
+ *
678
+ * // When done with subscription:
679
+ * builder.dispose();
680
+ * ```
681
+ */
682
+ countSubscribe(callback: (count: number) => void): Promise<number>;
683
+ /**
684
+ * Gets a page of results with pagination metadata.
685
+ *
686
+ * @param pageSize - Number of items per page
687
+ * @param pageNumber - Which page to retrieve (1-based)
688
+ * @returns Paginated results with metadata
689
+ *
690
+ * @example
691
+ * ```typescript
692
+ * const page = await Recipe.query(perspective)
693
+ * .where({ category: "Main" })
694
+ * .paginate(10, 1);
695
+ * console.log(`Page ${page.pageNumber}, ${page.results.length} of ${page.totalCount}`);
696
+ * ```
697
+ */
698
+ paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
699
+ /**
700
+ * Subscribes to paginated results updates.
701
+ *
702
+ * This method:
703
+ * 1. Creates and initializes a Prolog query subscription for the paginated results
704
+ * 2. Sets up the callback to process future page updates
705
+ * 3. Returns the initial page immediately
706
+ *
707
+ * Remember to call dispose() when you're done with the subscription
708
+ * to clean up resources.
709
+ *
710
+ * @param pageSize - Number of items per page
711
+ * @param pageNumber - Which page to retrieve (1-based)
712
+ * @param callback - Function to call with updated pagination results
713
+ * @returns Initial pagination results
714
+ *
715
+ * @example
716
+ * ```typescript
717
+ * const builder = Recipe.query(perspective)
718
+ * .where({ category: "Main" });
719
+ *
720
+ * const initialPage = await builder.paginateSubscribe(10, 1, page => {
721
+ * console.log("Updated page:", page.results);
722
+ * });
723
+ *
724
+ * // When done with subscription:
725
+ * builder.dispose();
726
+ * ```
727
+ */
728
+ paginateSubscribe(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
729
+ }
730
+ export {};