@coasys/ad4m 0.12.0-rc1-dev.5 → 0.12.0-rc2

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 (161) hide show
  1. package/lib/index.cjs +4968 -4805
  2. package/lib/index.js +4936 -4801
  3. package/lib/src/agent/AgentClient.d.ts +4 -0
  4. package/lib/src/agent/AgentClient.js +34 -0
  5. package/lib/src/index.d.ts +2 -3
  6. package/lib/src/index.js +2 -3
  7. package/lib/src/model/Ad4mModel.d.ts +8 -812
  8. package/lib/src/model/Ad4mModel.js +78 -2390
  9. package/lib/src/model/ModelQueryBuilder.d.ts +370 -0
  10. package/lib/src/model/ModelQueryBuilder.js +556 -0
  11. package/lib/src/model/decorators.d.ts +2 -20
  12. package/lib/src/model/decorators.js +5 -410
  13. package/lib/src/model/hydration.d.ts +102 -0
  14. package/lib/src/model/hydration.js +709 -0
  15. package/lib/src/model/index.d.ts +20 -0
  16. package/lib/src/model/index.js +20 -0
  17. package/lib/src/model/{schema/fromJSONSchema.d.ts → json-schema.d.ts} +45 -12
  18. package/lib/src/model/json-schema.js +326 -0
  19. package/lib/src/model/prolog-facts.d.ts +37 -0
  20. package/lib/src/model/{prolog/generatePrologFacts.js → prolog-facts.js} +47 -52
  21. package/lib/src/model/query-common.d.ts +14 -0
  22. package/lib/src/model/query-common.js +36 -0
  23. package/lib/src/model/query-prolog.d.ts +15 -0
  24. package/lib/src/model/query-prolog.js +140 -0
  25. package/lib/src/model/query-surreal.d.ts +44 -0
  26. package/lib/src/model/query-surreal.js +249 -0
  27. package/lib/src/model/sdna.d.ts +14 -0
  28. package/lib/src/model/sdna.js +141 -0
  29. package/lib/src/model/shacl-gen.d.ts +31 -0
  30. package/lib/src/model/shacl-gen.js +246 -0
  31. package/lib/src/model/surreal-utils.d.ts +1 -1
  32. package/lib/src/model/types.d.ts +75 -96
  33. package/lib/src/model/types.js +4 -4
  34. package/lib/src/model/util.d.ts +4 -5
  35. package/lib/src/model/util.js +12 -32
  36. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -1
  37. package/lib/src/perspectives/PerspectiveProxy.d.ts +1 -1
  38. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +79 -0
  39. package/lib/src/perspectives/WakerSubscriptionManager.js +196 -0
  40. package/lib/src/runtime/RuntimeResolver.d.ts +14 -0
  41. package/lib/src/runtime/RuntimeResolver.js +73 -0
  42. package/lib/src/schema.gql +14 -0
  43. package/lib/src/typeDefs.js +14 -0
  44. package/package.json +13 -8
  45. package/src/agent/AgentClient.ts +45 -0
  46. package/src/index.ts +2 -3
  47. package/src/model/Ad4mModel.ts +1084 -3818
  48. package/src/model/ModelQueryBuilder.ts +617 -0
  49. package/src/model/Subject.ts +1 -1
  50. package/src/model/decorators.ts +17 -475
  51. package/src/model/hydration.ts +796 -0
  52. package/src/model/index.ts +21 -0
  53. package/src/model/json-schema.ts +424 -0
  54. package/src/model/prolog-facts.ts +145 -0
  55. package/src/model/query-common.ts +48 -0
  56. package/src/model/query-prolog.ts +148 -0
  57. package/src/model/query-surreal.ts +280 -0
  58. package/src/model/relation-filtering.test.ts +0 -1
  59. package/src/model/sdna.ts +170 -0
  60. package/src/model/shacl-gen.ts +292 -0
  61. package/src/model/surreal-utils.ts +1 -1
  62. package/src/model/types.ts +182 -0
  63. package/src/model/util.ts +13 -36
  64. package/src/perspectives/PerspectiveClient.ts +1 -1
  65. package/src/perspectives/PerspectiveProxy.ts +1 -1
  66. package/src/perspectives/WakerSubscriptionManager.ts +292 -0
  67. package/src/runtime/RuntimeResolver.ts +53 -0
  68. package/lib/src/Ad4mClient.test.d.ts +0 -1
  69. package/lib/src/Ad4mClient.test.js +0 -1204
  70. package/lib/src/Literal.test.d.ts +0 -1
  71. package/lib/src/Literal.test.js +0 -41
  72. package/lib/src/model/mutation.d.ts +0 -81
  73. package/lib/src/model/mutation.js +0 -317
  74. package/lib/src/model/parentUtils.d.ts +0 -32
  75. package/lib/src/model/parentUtils.js +0 -64
  76. package/lib/src/model/prolog/generatePrologFacts.d.ts +0 -36
  77. package/lib/src/model/prolog/index.d.ts +0 -1
  78. package/lib/src/model/prolog/index.js +0 -1
  79. package/lib/src/model/query/ModelQueryBuilder.d.ts +0 -82
  80. package/lib/src/model/query/ModelQueryBuilder.js +0 -115
  81. package/lib/src/model/query/QueryBuilder.d.ts +0 -101
  82. package/lib/src/model/query/QueryBuilder.js +0 -193
  83. package/lib/src/model/query/SurrealQueryBuilder.d.ts +0 -48
  84. package/lib/src/model/query/SurrealQueryBuilder.js +0 -371
  85. package/lib/src/model/query/fetchInstance.d.ts +0 -24
  86. package/lib/src/model/query/fetchInstance.js +0 -144
  87. package/lib/src/model/query/hydration.d.ts +0 -54
  88. package/lib/src/model/query/hydration.js +0 -214
  89. package/lib/src/model/query/operations.d.ts +0 -59
  90. package/lib/src/model/query/operations.js +0 -384
  91. package/lib/src/model/query/snapshot.d.ts +0 -59
  92. package/lib/src/model/query/snapshot.js +0 -106
  93. package/lib/src/model/query/surrealCompiler.d.ts +0 -42
  94. package/lib/src/model/query/surrealCompiler.js +0 -304
  95. package/lib/src/model/schema/fromJSONSchema.js +0 -264
  96. package/lib/src/model/schema/metadata.d.ts +0 -15
  97. package/lib/src/model/schema/metadata.js +0 -112
  98. package/lib/src/model/subscription.d.ts +0 -47
  99. package/lib/src/model/subscription.js +0 -231
  100. package/lib/src/model/transaction.d.ts +0 -27
  101. package/lib/src/model/transaction.js +0 -32
  102. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  103. package/lib/src/shims/type-graphql.d.ts +0 -32
  104. package/lib/src/src/Ad4mClient.d.ts +0 -28
  105. package/lib/src/src/Address.d.ts +0 -1
  106. package/lib/src/src/DID.d.ts +0 -1
  107. package/lib/src/src/Exception.d.ts +0 -7
  108. package/lib/src/src/Literal.d.ts +0 -7
  109. package/lib/src/src/PubSub.d.ts +0 -17
  110. package/lib/src/src/SmartLiteral.d.ts +0 -12
  111. package/lib/src/src/agent/Agent.d.ts +0 -110
  112. package/lib/src/src/agent/AgentClient.d.ts +0 -62
  113. package/lib/src/src/agent/AgentResolver.d.ts +0 -30
  114. package/lib/src/src/agent/AgentStatus.d.ts +0 -8
  115. package/lib/src/src/ai/AIClient.d.ts +0 -32
  116. package/lib/src/src/ai/AIResolver.d.ts +0 -75
  117. package/lib/src/src/ai/Tasks.d.ts +0 -37
  118. package/lib/src/src/buildSchema.d.ts +0 -1
  119. package/lib/src/src/expression/Expression.d.ts +0 -28
  120. package/lib/src/src/expression/ExpressionClient.d.ts +0 -13
  121. package/lib/src/src/expression/ExpressionRef.d.ts +0 -9
  122. package/lib/src/src/expression/ExpressionResolver.d.ts +0 -10
  123. package/lib/src/src/index.d.ts +0 -35
  124. package/lib/src/src/jestSetup.d.ts +0 -1
  125. package/lib/src/src/language/Icon.d.ts +0 -4
  126. package/lib/src/src/language/Language.d.ts +0 -206
  127. package/lib/src/src/language/LanguageClient.d.ts +0 -17
  128. package/lib/src/src/language/LanguageContext.d.ts +0 -37
  129. package/lib/src/src/language/LanguageHandle.d.ts +0 -9
  130. package/lib/src/src/language/LanguageMeta.d.ts +0 -35
  131. package/lib/src/src/language/LanguageRef.d.ts +0 -6
  132. package/lib/src/src/language/LanguageResolver.d.ts +0 -19
  133. package/lib/src/src/links/Links.d.ts +0 -39
  134. package/lib/src/src/links/Links.test.d.ts +0 -1
  135. package/lib/src/src/model/Ad4mModel.d.ts +0 -1438
  136. package/lib/src/src/model/Ad4mModel.test.d.ts +0 -1
  137. package/lib/src/src/model/Subject.d.ts +0 -25
  138. package/lib/src/src/model/decorators.d.ts +0 -545
  139. package/lib/src/src/model/util.d.ts +0 -12
  140. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +0 -10
  141. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +0 -25
  142. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +0 -19
  143. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +0 -1
  144. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +0 -24
  145. package/lib/src/src/perspectives/LinkQuery.d.ts +0 -11
  146. package/lib/src/src/perspectives/Perspective.d.ts +0 -38
  147. package/lib/src/src/perspectives/Perspective.test.d.ts +0 -1
  148. package/lib/src/src/perspectives/PerspectiveClient.d.ts +0 -97
  149. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +0 -9
  150. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +0 -18
  151. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +0 -865
  152. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +0 -57
  153. package/lib/src/src/runtime/RuntimeClient.d.ts +0 -56
  154. package/lib/src/src/runtime/RuntimeResolver.d.ts +0 -132
  155. package/lib/src/src/shacl/SHACLFlow.d.ts +0 -171
  156. package/lib/src/src/shacl/SHACLFlow.test.d.ts +0 -1
  157. package/lib/src/src/shacl/SHACLShape.d.ts +0 -117
  158. package/lib/src/src/shacl/SHACLShape.test.d.ts +0 -1
  159. package/lib/src/src/typeDefs.d.ts +0 -1
  160. package/lib/src/src/unwrapApolloResult.d.ts +0 -2
  161. package/lib/src/src/utils.d.ts +0 -25
@@ -0,0 +1,370 @@
1
+ /**
2
+ * ModelQueryBuilder — fluent query builder for Ad4mModel.
3
+ *
4
+ * Allows building queries with a chainable interface and either
5
+ * running them once or subscribing to real-time updates.
6
+ */
7
+ import type { Ad4mModel } from "./Ad4mModel";
8
+ import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
9
+ import type { Where, Order, IncludeMap, Query, PaginationResult } from "./types";
10
+ /** Query builder for Ad4mModel queries.
11
+ * Allows building queries with a fluent interface and either running them once
12
+ * or subscribing to updates.
13
+ *
14
+ * @example
15
+ * ```typescript
16
+ * const builder = Recipe.query(perspective)
17
+ * .where({ category: "Dessert" })
18
+ * .order({ rating: "DESC" })
19
+ * .limit(10);
20
+ *
21
+ * // Run once
22
+ * const recipes = await builder.run();
23
+ *
24
+ * // Or subscribe to updates
25
+ * await builder.subscribe(recipes => {
26
+ * console.log("Updated recipes:", recipes);
27
+ * });
28
+ * ```
29
+ */
30
+ export declare class ModelQueryBuilder<T extends Ad4mModel> {
31
+ private perspective;
32
+ private queryParams;
33
+ private modelClassName;
34
+ private ctor;
35
+ private currentSubscription?;
36
+ private useSurrealDBFlag;
37
+ constructor(perspective: PerspectiveProxy, ctor: typeof Ad4mModel, query?: Query);
38
+ /**
39
+ * Disposes of the current subscription if one exists.
40
+ *
41
+ * This method:
42
+ * 1. Stops the keepalive signals to the subscription
43
+ * 2. Unsubscribes from GraphQL subscription updates
44
+ * 3. Notifies the backend to clean up subscription resources
45
+ * 4. Clears the subscription reference
46
+ *
47
+ * You should call this method when you're done with a subscription
48
+ * to prevent memory leaks and ensure proper cleanup.
49
+ */
50
+ dispose(): void;
51
+ /**
52
+ * Adds where conditions to the query.
53
+ *
54
+ * @param conditions - The conditions to filter by
55
+ * @returns The query builder for chaining
56
+ *
57
+ * @example
58
+ * ```typescript
59
+ * .where({
60
+ * category: "Dessert",
61
+ * rating: { gt: 4 },
62
+ * tags: ["vegan", "quick"],
63
+ * published: true
64
+ * })
65
+ * ```
66
+ */
67
+ where(conditions: Where): ModelQueryBuilder<T>;
68
+ /**
69
+ * Sets the order for the query results.
70
+ *
71
+ * @param orderBy - The ordering criteria
72
+ * @returns The query builder for chaining
73
+ *
74
+ * @example
75
+ * ```typescript
76
+ * .order({ createdAt: "DESC" })
77
+ * ```
78
+ */
79
+ order(orderBy: Order): ModelQueryBuilder<T>;
80
+ /**
81
+ * Sets the maximum number of results to return.
82
+ *
83
+ * @param limit - Maximum number of results
84
+ * @returns The query builder for chaining
85
+ *
86
+ * @example
87
+ * ```typescript
88
+ * .limit(10)
89
+ * ```
90
+ */
91
+ limit(limit: number): ModelQueryBuilder<T>;
92
+ /**
93
+ * Sets the number of results to skip.
94
+ *
95
+ * @param offset - Number of results to skip
96
+ * @returns The query builder for chaining
97
+ *
98
+ * @example
99
+ * ```typescript
100
+ * .offset(20) // Skip first 20 results
101
+ * ```
102
+ */
103
+ offset(offset: number): ModelQueryBuilder<T>;
104
+ /**
105
+ * Scopes the query to instances linked from a parent.
106
+ *
107
+ * The predicate is resolved in order of precedence:
108
+ * 1. **Instance only** — the parent's constructor is used as the model
109
+ * class; its relation metadata is scanned for a relation whose
110
+ * `target()` matches the queried model class.
111
+ * 2. **Instance + options with `field`** — direct field-name lookup on
112
+ * the parent model's relation metadata (disambiguates when a parent
113
+ * has multiple relations targeting the same child class).
114
+ * 3. **String id + model class** — same metadata scan (or field lookup if
115
+ * options include `field`).
116
+ * 4. **String id + string predicate** — raw escape hatch, no metadata lookup.
117
+ *
118
+ * Passing a plain string id with no second argument throws because the
119
+ * predicate cannot be resolved without a model class.
120
+ *
121
+ * @param idOrInstance - The parent's expression URI **or** an Ad4mModel instance
122
+ * @param modelOrPredicate - A model class (predicate auto-resolved) **or** a raw predicate string
123
+ * @param options - Optional settings: `field` for direct relation-name lookup
124
+ * @returns The query builder for chaining
125
+ *
126
+ * @example
127
+ * ```typescript
128
+ * // Instance — predicate auto-resolved from Cookbook's @HasMany(() => Recipe)
129
+ * Recipe.query(perspective).parent(cookbook).get();
130
+ *
131
+ * // Instance + field — disambiguate when parent has multiple relations to same child
132
+ * Recipe.query(perspective).parent(cookbook, { field: "recipes" }).get();
133
+ *
134
+ * // String id + model class
135
+ * Recipe.query(perspective).parent(cookbookId, Cookbook).get();
136
+ *
137
+ * // String id + model class + field
138
+ * Recipe.query(perspective).parent(cookbookId, Cookbook, { field: "recipes" }).get();
139
+ *
140
+ * // String id + raw predicate (escape hatch)
141
+ * Recipe.query(perspective).parent(cookbookId, "cookbook://recipe").get();
142
+ * ```
143
+ */
144
+ parent(idOrInstance: string | Ad4mModel, modelOrPredicate?: typeof Ad4mModel | string | {
145
+ field: string;
146
+ }, options?: {
147
+ field?: string;
148
+ }): ModelQueryBuilder<T>;
149
+ /**
150
+ * Specifies which properties to include in the results.
151
+ *
152
+ * @param properties - Array of property names to include
153
+ * @returns The query builder for chaining
154
+ *
155
+ * @example
156
+ * ```typescript
157
+ * .properties(["name", "description", "rating"])
158
+ * ```
159
+ */
160
+ properties(properties: string[]): ModelQueryBuilder<T>;
161
+ /**
162
+ * Specifies which relations to eager-load (hydrate into model instances).
163
+ *
164
+ * Without `include`, relation fields contain raw expression URIs (strings).
165
+ * With `include`, the URIs are resolved into fully-hydrated model instances
166
+ * using the `target` class declared in the relation decorator.
167
+ *
168
+ * Supports nested includes for multi-level eager loading.
169
+ *
170
+ * @param map - An IncludeMap describing which relations to hydrate
171
+ * @returns The query builder for chaining
172
+ *
173
+ * @example
174
+ * ```typescript
175
+ * // Hydrate comments one level deep
176
+ * const recipes = await Recipe.query(perspective)
177
+ * .include({ comments: true })
178
+ * .run();
179
+ * // recipe.comments is now Comment[] (model instances), not string[]
180
+ *
181
+ * // Nested: hydrate comments AND each comment's author
182
+ * const recipes = await Recipe.query(perspective)
183
+ * .include({ comments: { author: true } })
184
+ * .run();
185
+ * ```
186
+ */
187
+ include(map: IncludeMap): ModelQueryBuilder<T>;
188
+ overrideModelClassName(className: string): ModelQueryBuilder<T>;
189
+ /**
190
+ * Enables or disables SurrealDB query path.
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).
213
+ */
214
+ useSurrealDB(enabled?: boolean): ModelQueryBuilder<T>;
215
+ /**
216
+ * Executes the query once and returns the results.
217
+ *
218
+ * @returns Array of matching entities
219
+ *
220
+ * @example
221
+ * ```typescript
222
+ * const recipes = await Recipe.query(perspective)
223
+ * .where({ category: "Dessert" })
224
+ * .get();
225
+ * ```
226
+ */
227
+ get(): Promise<T[]>;
228
+ /**
229
+ * Returns the first matching instance, or `null` if none match.
230
+ *
231
+ * Internally sets `limit: 1` and delegates to `get()`.
232
+ *
233
+ * @returns The first matching instance, or `null`
234
+ *
235
+ * @example
236
+ * ```typescript
237
+ * const recipe = await Recipe.query(perspective)
238
+ * .where({ name: "Pasta" })
239
+ * .first();
240
+ * ```
241
+ */
242
+ first(): Promise<T | null>;
243
+ /**
244
+ * Subscribes to the query and receives updates when results change.
245
+ *
246
+ * This method:
247
+ * 1. Creates and initializes a SurrealDB live query subscription (default)
248
+ * 2. Sets up the callback to process future updates
249
+ * 3. Returns the initial results immediately
250
+ *
251
+ * Remember to call dispose() when you're done with the subscription
252
+ * to clean up resources.
253
+ *
254
+ * @param callback - Function to call with updated results
255
+ * @returns Initial results array
256
+ *
257
+ * @example
258
+ * ```typescript
259
+ * const builder = Recipe.query(perspective)
260
+ * .where({ status: "cooking" });
261
+ *
262
+ * const initialRecipes = await builder.subscribe(recipes => {
263
+ * console.log("Updated recipes:", recipes);
264
+ * });
265
+ *
266
+ * // When done with subscription:
267
+ * builder.dispose();
268
+ * ```
269
+ *
270
+ * @remarks
271
+ * By default, this uses SurrealDB live queries for real-time updates.
272
+ * Prolog subscriptions remain available via `.useSurrealDB(false)`.
273
+ */
274
+ subscribe(callback: (results: T[]) => void): Promise<T[]>;
275
+ /**
276
+ * Gets the total count of matching entities.
277
+ *
278
+ * @returns Total count
279
+ *
280
+ * @example
281
+ * ```typescript
282
+ * const totalDesserts = await Recipe.query(perspective)
283
+ * .where({ category: "Dessert" })
284
+ * .count();
285
+ * ```
286
+ */
287
+ count(): Promise<number>;
288
+ /**
289
+ * Subscribes to count updates for matching entities.
290
+ *
291
+ * This method:
292
+ * 1. Creates and initializes a SurrealDB live query subscription for the count (default)
293
+ * 2. Sets up the callback to process future count updates
294
+ * 3. Returns the initial count immediately
295
+ *
296
+ * Remember to call dispose() when you're done with the subscription
297
+ * to clean up resources.
298
+ *
299
+ * @param callback - Function to call with updated count
300
+ * @returns Initial count
301
+ *
302
+ * @example
303
+ * ```typescript
304
+ * const builder = Recipe.query(perspective)
305
+ * .where({ status: "active" });
306
+ *
307
+ * const initialCount = await builder.countSubscribe(count => {
308
+ * console.log("Active items:", count);
309
+ * });
310
+ *
311
+ * // When done with subscription:
312
+ * builder.dispose();
313
+ * ```
314
+ *
315
+ * @remarks
316
+ * By default, this uses SurrealDB live queries for real-time updates.
317
+ * Prolog subscriptions remain available via `.useSurrealDB(false)`.
318
+ */
319
+ countSubscribe(callback: (count: number) => void): Promise<number>;
320
+ /**
321
+ * Gets a page of results with pagination metadata.
322
+ *
323
+ * @param pageSize - Number of items per page
324
+ * @param pageNumber - Which page to retrieve (1-based)
325
+ * @returns Paginated results with metadata
326
+ *
327
+ * @example
328
+ * ```typescript
329
+ * const page = await Recipe.query(perspective)
330
+ * .where({ category: "Main" })
331
+ * .paginate(10, 1);
332
+ * console.log(`Page ${page.pageNumber}, ${page.results.length} of ${page.totalCount}`);
333
+ * ```
334
+ */
335
+ paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
336
+ /**
337
+ * Subscribes to paginated results updates.
338
+ *
339
+ * This method:
340
+ * 1. Creates and initializes a SurrealDB live query subscription for the paginated results (default)
341
+ * 2. Sets up the callback to process future page updates
342
+ * 3. Returns the initial page immediately
343
+ *
344
+ * Remember to call dispose() when you're done with the subscription
345
+ * to clean up resources.
346
+ *
347
+ * @param pageSize - Number of items per page
348
+ * @param pageNumber - Which page to retrieve (1-based)
349
+ * @param callback - Function to call with updated pagination results
350
+ * @returns Initial pagination results
351
+ *
352
+ * @example
353
+ * ```typescript
354
+ * const builder = Recipe.query(perspective)
355
+ * .where({ category: "Main" });
356
+ *
357
+ * const initialPage = await builder.paginateSubscribe(10, 1, page => {
358
+ * console.log("Updated page:", page.results);
359
+ * });
360
+ *
361
+ * // When done with subscription:
362
+ * builder.dispose();
363
+ * ```
364
+ *
365
+ * @remarks
366
+ * By default, this uses SurrealDB live queries for real-time updates.
367
+ * Prolog subscriptions remain available via `.useSurrealDB(false)`.
368
+ */
369
+ paginateSubscribe(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
370
+ }