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