@coasys/ad4m 0.12.0-rc1-dev.1 → 0.12.0-rc1-dev.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/jest.config.js +4 -4
  2. package/lib/index.cjs +5999 -6046
  3. package/lib/index.js +5977 -6040
  4. package/lib/src/Ad4mClient.d.ts +16 -9
  5. package/lib/src/Ad4mClient.js +25 -46
  6. package/lib/src/Ad4mClient.test.d.ts +1 -0
  7. package/lib/src/Ad4mClient.test.js +1204 -0
  8. package/lib/src/Literal.d.ts +2 -1
  9. package/lib/src/Literal.js +35 -38
  10. package/lib/src/Literal.test.d.ts +1 -0
  11. package/lib/src/Literal.test.js +41 -0
  12. package/lib/src/SmartLiteral.d.ts +2 -1
  13. package/lib/src/SmartLiteral.js +15 -30
  14. package/lib/src/agent/AgentClient.d.ts +4 -1
  15. package/lib/src/agent/AgentClient.js +99 -79
  16. package/lib/src/ai/AIClient.d.ts +2 -1
  17. package/lib/src/ai/AIClient.js +220 -224
  18. package/lib/src/expression/ExpressionClient.d.ts +1 -1
  19. package/lib/src/expression/ExpressionClient.js +86 -73
  20. package/lib/src/index.d.ts +1 -1
  21. package/lib/src/index.js +1 -1
  22. package/lib/src/language/LanguageClient.d.ts +1 -1
  23. package/lib/src/language/LanguageClient.js +52 -52
  24. package/lib/src/model/Ad4mModel.d.ts +157 -937
  25. package/lib/src/model/Ad4mModel.js +212 -2799
  26. package/lib/src/model/Ad4mModel.test.js +1002 -561
  27. package/lib/src/model/decorators.d.ts +94 -426
  28. package/lib/src/model/decorators.js +333 -741
  29. package/lib/src/model/mutation.d.ts +81 -0
  30. package/lib/src/model/mutation.js +317 -0
  31. package/lib/src/model/parentUtils.d.ts +32 -0
  32. package/lib/src/model/parentUtils.js +64 -0
  33. package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
  34. package/lib/src/model/prolog/generatePrologFacts.js +139 -0
  35. package/lib/src/model/prolog/index.d.ts +1 -0
  36. package/lib/src/model/prolog/index.js +1 -0
  37. package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
  38. package/lib/src/model/query/ModelQueryBuilder.js +115 -0
  39. package/lib/src/model/query/QueryBuilder.d.ts +101 -0
  40. package/lib/src/model/query/QueryBuilder.js +193 -0
  41. package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
  42. package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
  43. package/lib/src/model/query/fetchInstance.d.ts +24 -0
  44. package/lib/src/model/query/fetchInstance.js +144 -0
  45. package/lib/src/model/query/hydration.d.ts +54 -0
  46. package/lib/src/model/query/hydration.js +214 -0
  47. package/lib/src/model/query/operations.d.ts +59 -0
  48. package/lib/src/model/query/operations.js +384 -0
  49. package/lib/src/model/query/snapshot.d.ts +59 -0
  50. package/lib/src/model/query/snapshot.js +106 -0
  51. package/lib/src/model/query/surrealCompiler.d.ts +42 -0
  52. package/lib/src/model/query/surrealCompiler.js +304 -0
  53. package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
  54. package/lib/src/model/schema/fromJSONSchema.js +264 -0
  55. package/lib/src/model/schema/metadata.d.ts +15 -0
  56. package/lib/src/model/schema/metadata.js +112 -0
  57. package/lib/src/model/subscription.d.ts +47 -0
  58. package/lib/src/model/subscription.js +231 -0
  59. package/lib/src/model/transaction.d.ts +27 -0
  60. package/lib/src/model/transaction.js +32 -0
  61. package/lib/src/model/types.d.ts +195 -0
  62. package/lib/src/model/types.js +8 -0
  63. package/lib/src/model/util.js +7 -7
  64. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +5 -1
  65. package/lib/src/neighbourhood/NeighbourhoodClient.js +263 -181
  66. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -1
  67. package/lib/src/neighbourhood/NeighbourhoodProxy.js +13 -28
  68. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +1 -5
  69. package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
  70. package/lib/src/perspectives/PerspectiveClient.js +316 -240
  71. package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -92
  72. package/lib/src/perspectives/PerspectiveProxy.js +803 -444
  73. package/lib/src/runtime/RuntimeClient.d.ts +5 -1
  74. package/lib/src/runtime/RuntimeClient.js +412 -238
  75. package/lib/src/shacl/SHACLFlow.test.js +164 -105
  76. package/lib/src/shacl/SHACLShape.d.ts +17 -3
  77. package/lib/src/shacl/SHACLShape.js +127 -90
  78. package/lib/src/shacl/SHACLShape.test.js +244 -176
  79. package/lib/src/utils.d.ts +8 -0
  80. package/lib/src/utils.js +21 -7
  81. package/package.json +8 -13
  82. package/src/Ad4mClient.test.ts +1564 -1315
  83. package/src/Ad4mClient.ts +55 -54
  84. package/src/Literal.test.ts +45 -26
  85. package/src/Literal.ts +82 -66
  86. package/src/SmartLiteral.ts +74 -58
  87. package/src/agent/AgentClient.ts +144 -99
  88. package/src/ai/AIClient.ts +409 -359
  89. package/src/expression/ExpressionClient.ts +142 -96
  90. package/src/index.ts +1 -1
  91. package/src/language/LanguageClient.ts +137 -113
  92. package/src/model/Ad4mModel.test.ts +1128 -647
  93. package/src/model/Ad4mModel.ts +485 -3249
  94. package/src/model/IMPROVEMENTS.md +482 -0
  95. package/src/model/PREDICATE_COLLISION_FIX.md +651 -0
  96. package/src/model/README.md +317 -0
  97. package/src/model/SHACL_MUTATION_DECOUPLING.md +356 -0
  98. package/src/model/SUBSCRIPTION_STRATEGY.md +317 -0
  99. package/src/model/TC39_STAGE_3_DECORATORS.md +609 -0
  100. package/src/model/decorators.ts +689 -1046
  101. package/src/model/mutation.ts +461 -0
  102. package/src/model/parentUtils.ts +91 -0
  103. package/src/model/prolog/generatePrologFacts.ts +176 -0
  104. package/src/model/prolog/index.ts +1 -0
  105. package/src/model/query/ModelQueryBuilder.ts +173 -0
  106. package/src/model/query/fetchInstance.ts +181 -0
  107. package/src/model/query/hydration.ts +273 -0
  108. package/src/model/query/operations.ts +510 -0
  109. package/src/model/query/snapshot.ts +126 -0
  110. package/src/model/query/surrealCompiler.ts +376 -0
  111. package/src/model/schema/fromJSONSchema.ts +411 -0
  112. package/src/model/schema/metadata.ts +148 -0
  113. package/src/model/subscription.ts +307 -0
  114. package/src/model/transaction.ts +60 -0
  115. package/src/model/types.ts +207 -0
  116. package/src/model/util.ts +47 -48
  117. package/src/neighbourhood/NeighbourhoodClient.ts +393 -251
  118. package/src/neighbourhood/NeighbourhoodProxy.test.ts +3 -7
  119. package/src/neighbourhood/NeighbourhoodProxy.ts +58 -40
  120. package/src/perspectives/PerspectiveClient.ts +779 -540
  121. package/src/perspectives/PerspectiveProxy.ts +2860 -2053
  122. package/src/runtime/RuntimeClient.ts +775 -476
  123. package/src/shacl/SHACLFlow.test.ts +196 -129
  124. package/src/shacl/SHACLShape.test.ts +284 -190
  125. package/src/shacl/SHACLShape.ts +225 -172
  126. package/src/utils.ts +31 -17
  127. package/tsconfig.json +9 -10
  128. package/src/model/Subject.ts +0 -159
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Fluent query builder for Ad4mModel.
3
+ *
4
+ * Extracted from Ad4mModel.ts. The class holds a `Query` object and delegates
5
+ * all execution to `Ad4mModel` static methods via the `ctor` constructor
6
+ * reference, so there is no circular import (this module imports from the
7
+ * Ad4mModel module, but Ad4mModel does not import from here — it re-exports
8
+ * ModelQueryBuilder from its own file for backward compatibility).
9
+ */
10
+ import { PerspectiveProxy } from "../../perspectives/PerspectiveProxy";
11
+ import { Order, PaginationResult, Query, Where, IncludeMap, SubscribeOptions, Subscription } from "../types";
12
+ export type Ad4mModelCtor<T> = typeof import("../Ad4mModel").Ad4mModel & (new (...args: any[]) => T);
13
+ /**
14
+ * Fluent builder for Ad4mModel queries.
15
+ *
16
+ * Create via `MyModel.query(perspective)`:
17
+ * ```typescript
18
+ * const posts = await Post.query(perspective)
19
+ * .where({ published: true })
20
+ * .order({ createdAt: "DESC" })
21
+ * .limit(10)
22
+ * .get();
23
+ * ```
24
+ */
25
+ export declare class ModelQueryBuilder<T extends import("../Ad4mModel").Ad4mModel> {
26
+ private perspective;
27
+ private queryParams;
28
+ private modelClassName;
29
+ private ctor;
30
+ constructor(perspective: PerspectiveProxy, ctor: Ad4mModelCtor<T>, query?: Query);
31
+ where(conditions: Where): ModelQueryBuilder<T>;
32
+ order(orderBy: Order): ModelQueryBuilder<T>;
33
+ limit(limit: number): ModelQueryBuilder<T>;
34
+ offset(offset: number): ModelQueryBuilder<T>;
35
+ properties(properties: string[]): ModelQueryBuilder<T>;
36
+ /**
37
+ * Eagerly load specific relations as full model instances.
38
+ *
39
+ * Key = relation field name on the model.
40
+ * Value = `true` (all instances) or a `Query` to filter/order/limit the nested set.
41
+ *
42
+ * @example
43
+ * ```typescript
44
+ * Recipe.query(perspective)
45
+ * .include({
46
+ * comments: true,
47
+ * tags: { where: { active: true }, limit: 5 },
48
+ * })
49
+ * .get();
50
+ * ```
51
+ */
52
+ include(map: IncludeMap): ModelQueryBuilder<T>;
53
+ overrideModelClassName(className: string): ModelQueryBuilder<T>;
54
+ /** Executes the query and returns all matching instances. */
55
+ get(): Promise<T[]>;
56
+ /** Returns the first matching instance, or `null` if none found. */
57
+ first(): Promise<T | null>;
58
+ /** Returns the total count of matching entities. */
59
+ count(): Promise<number>;
60
+ /** Returns a single page of results with pagination metadata. */
61
+ paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
62
+ /**
63
+ * Terminal: creates a live subscription using the query parameters accumulated
64
+ * so far. Fires `callback` immediately with current results, then on every
65
+ * relevant link change.
66
+ *
67
+ * Pass additional delivery options (`debounce`, `onError`) in `deliveryOpts`.
68
+ * Call `sub.unsubscribe()` to detach.
69
+ *
70
+ * @example
71
+ * ```typescript
72
+ * const sub = Post.query(perspective)
73
+ * .where({ published: true })
74
+ * .order({ createdAt: "DESC" })
75
+ * .live((posts) => setPosts(posts), { debounce: 300 });
76
+ *
77
+ * // cleanup:
78
+ * sub.unsubscribe();
79
+ * ```
80
+ */
81
+ live(callback: (results: T[]) => void, deliveryOpts?: Pick<SubscribeOptions, "debounce" | "onError">): Subscription;
82
+ }
@@ -0,0 +1,115 @@
1
+ /**
2
+ * Fluent query builder for Ad4mModel.
3
+ *
4
+ * Extracted from Ad4mModel.ts. The class holds a `Query` object and delegates
5
+ * all execution to `Ad4mModel` static methods via the `ctor` constructor
6
+ * reference, so there is no circular import (this module imports from the
7
+ * Ad4mModel module, but Ad4mModel does not import from here — it re-exports
8
+ * ModelQueryBuilder from its own file for backward compatibility).
9
+ */
10
+ import { createSubscription } from "../subscription";
11
+ /**
12
+ * Fluent builder for Ad4mModel queries.
13
+ *
14
+ * Create via `MyModel.query(perspective)`:
15
+ * ```typescript
16
+ * const posts = await Post.query(perspective)
17
+ * .where({ published: true })
18
+ * .order({ createdAt: "DESC" })
19
+ * .limit(10)
20
+ * .get();
21
+ * ```
22
+ */
23
+ export class ModelQueryBuilder {
24
+ constructor(perspective, ctor, query) {
25
+ this.queryParams = {};
26
+ this.modelClassName = null;
27
+ this.perspective = perspective;
28
+ this.ctor = ctor;
29
+ if (query)
30
+ this.queryParams = query;
31
+ }
32
+ where(conditions) {
33
+ this.queryParams.where = conditions;
34
+ return this;
35
+ }
36
+ order(orderBy) {
37
+ this.queryParams.order = orderBy;
38
+ return this;
39
+ }
40
+ limit(limit) {
41
+ this.queryParams.limit = limit;
42
+ return this;
43
+ }
44
+ offset(offset) {
45
+ this.queryParams.offset = offset;
46
+ return this;
47
+ }
48
+ properties(properties) {
49
+ this.queryParams.properties = properties;
50
+ return this;
51
+ }
52
+ /**
53
+ * Eagerly load specific relations as full model instances.
54
+ *
55
+ * Key = relation field name on the model.
56
+ * Value = `true` (all instances) or a `Query` to filter/order/limit the nested set.
57
+ *
58
+ * @example
59
+ * ```typescript
60
+ * Recipe.query(perspective)
61
+ * .include({
62
+ * comments: true,
63
+ * tags: { where: { active: true }, limit: 5 },
64
+ * })
65
+ * .get();
66
+ * ```
67
+ */
68
+ include(map) {
69
+ this.queryParams.include = map;
70
+ return this;
71
+ }
72
+ overrideModelClassName(className) {
73
+ this.modelClassName = className;
74
+ return this;
75
+ }
76
+ /** Executes the query and returns all matching instances. */
77
+ async get() {
78
+ return this.ctor.findAll(this.perspective, this.queryParams);
79
+ }
80
+ /** Returns the first matching instance, or `null` if none found. */
81
+ async first() {
82
+ return this.ctor.findOne(this.perspective, this.queryParams);
83
+ }
84
+ /** Returns the total count of matching entities. */
85
+ async count() {
86
+ return this.ctor.count(this.perspective, this.queryParams);
87
+ }
88
+ /** Returns a single page of results with pagination metadata. */
89
+ async paginate(pageSize, pageNumber) {
90
+ return this.ctor.paginate(this.perspective, pageSize, pageNumber, this.queryParams);
91
+ }
92
+ /**
93
+ * Terminal: creates a live subscription using the query parameters accumulated
94
+ * so far. Fires `callback` immediately with current results, then on every
95
+ * relevant link change.
96
+ *
97
+ * Pass additional delivery options (`debounce`, `onError`) in `deliveryOpts`.
98
+ * Call `sub.unsubscribe()` to detach.
99
+ *
100
+ * @example
101
+ * ```typescript
102
+ * const sub = Post.query(perspective)
103
+ * .where({ published: true })
104
+ * .order({ createdAt: "DESC" })
105
+ * .live((posts) => setPosts(posts), { debounce: 300 });
106
+ *
107
+ * // cleanup:
108
+ * sub.unsubscribe();
109
+ * ```
110
+ */
111
+ live(callback, deliveryOpts) {
112
+ const options = { ...this.queryParams, ...deliveryOpts };
113
+ return createSubscription((p, q) => this.ctor.findAll(p, q ?? {}), () => this.ctor.getModelMetadata(), this.perspective, options, callback, this.ctor);
114
+ }
115
+ }
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Fluent query builder for Ad4mModel.
3
+ *
4
+ * Extracted from Ad4mModel.ts. The class holds a `Query` object and delegates
5
+ * all execution to `Ad4mModel` static methods via the `ctor` constructor
6
+ * reference, so there is no circular import (this module imports from the
7
+ * Ad4mModel module, but Ad4mModel does not import from here — it re-exports
8
+ * ModelQueryBuilder from its own file for backward compatibility).
9
+ */
10
+ import { PerspectiveProxy } from "../../perspectives/PerspectiveProxy";
11
+ import { Order, PaginationResult, Query, Where, IncludeMap, SubscribeOptions, Subscription } from "../types";
12
+ export type Ad4mModelCtor<T> = typeof import("../Ad4mModel").Ad4mModel & (new (...args: any[]) => T);
13
+ /**
14
+ * Fluent builder for Ad4mModel queries.
15
+ *
16
+ * Create via `MyModel.query(perspective)`:
17
+ * ```typescript
18
+ * const posts = await Post.query(perspective)
19
+ * .where({ published: true })
20
+ * .order({ createdAt: "DESC" })
21
+ * .limit(10)
22
+ * .get();
23
+ * ```
24
+ */
25
+ export declare class ModelQueryBuilder<T extends import("../Ad4mModel").Ad4mModel> {
26
+ private perspective;
27
+ private queryParams;
28
+ private modelClassName;
29
+ private ctor;
30
+ private currentSubscription?;
31
+ constructor(perspective: PerspectiveProxy, ctor: Ad4mModelCtor<T>, query?: Query);
32
+ /**
33
+ * Disposes of the current live subscription (if any).
34
+ * Call when done to avoid memory leaks.
35
+ */
36
+ dispose(): void;
37
+ where(conditions: Where): ModelQueryBuilder<T>;
38
+ order(orderBy: Order): ModelQueryBuilder<T>;
39
+ limit(limit: number): ModelQueryBuilder<T>;
40
+ offset(offset: number): ModelQueryBuilder<T>;
41
+ properties(properties: string[]): ModelQueryBuilder<T>;
42
+ /**
43
+ * Eagerly load specific relations as full model instances.
44
+ *
45
+ * Key = relation field name on the model.
46
+ * Value = `true` (all instances) or a `Query` to filter/order/limit the nested set.
47
+ *
48
+ * @example
49
+ * ```typescript
50
+ * Recipe.query(perspective)
51
+ * .include({
52
+ * comments: true,
53
+ * tags: { where: { active: true }, limit: 5 },
54
+ * })
55
+ * .get();
56
+ * ```
57
+ */
58
+ include(map: IncludeMap): ModelQueryBuilder<T>;
59
+ overrideModelClassName(className: string): ModelQueryBuilder<T>;
60
+ /**
61
+ * Executes the query once and returns the results.
62
+ */
63
+ get(): Promise<T[]>;
64
+ /**
65
+ * Subscribes to live updates and returns initial results.
66
+ * Call `dispose()` when done.
67
+ */
68
+ subscribe(callback: (results: T[]) => void): Promise<T[]>;
69
+ /** Returns the total count of matching entities. */
70
+ count(): Promise<number>;
71
+ /**
72
+ * Subscribes to count updates. Call `dispose()` when done.
73
+ */
74
+ countSubscribe(callback: (count: number) => void): Promise<number>;
75
+ /** Returns a single page of results with pagination metadata. */
76
+ paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
77
+ /**
78
+ * Subscribes to paginated live updates. Call `dispose()` when done.
79
+ */
80
+ paginateSubscribe(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
81
+ /**
82
+ * Terminal: creates a live subscription using the query parameters accumulated
83
+ * so far. Fires `callback` immediately with current results, then on every
84
+ * relevant link change.
85
+ *
86
+ * Pass additional delivery options (`debounce`, `onError`) in `deliveryOpts`.
87
+ * Call `sub.unsubscribe()` to detach.
88
+ *
89
+ * @example
90
+ * ```typescript
91
+ * const sub = Post.query(perspective)
92
+ * .where({ published: true })
93
+ * .order({ createdAt: "DESC" })
94
+ * .live((posts) => setPosts(posts), { debounce: 300 });
95
+ *
96
+ * // cleanup:
97
+ * sub.unsubscribe();
98
+ * ```
99
+ */
100
+ live(callback: (results: T[]) => void, deliveryOpts?: Pick<SubscribeOptions, "debounce" | "onError">): Subscription;
101
+ }
@@ -0,0 +1,193 @@
1
+ /**
2
+ * Fluent query builder for Ad4mModel.
3
+ *
4
+ * Extracted from Ad4mModel.ts. The class holds a `Query` object and delegates
5
+ * all execution to `Ad4mModel` static methods via the `ctor` constructor
6
+ * reference, so there is no circular import (this module imports from the
7
+ * Ad4mModel module, but Ad4mModel does not import from here — it re-exports
8
+ * ModelQueryBuilder from its own file for backward compatibility).
9
+ */
10
+ import { createSubscription } from "../subscription";
11
+ /**
12
+ * Fluent builder for Ad4mModel queries.
13
+ *
14
+ * Create via `MyModel.query(perspective)`:
15
+ * ```typescript
16
+ * const posts = await Post.query(perspective)
17
+ * .where({ published: true })
18
+ * .order({ createdAt: "DESC" })
19
+ * .limit(10)
20
+ * .get();
21
+ * ```
22
+ */
23
+ export class ModelQueryBuilder {
24
+ constructor(perspective, ctor, query) {
25
+ this.queryParams = {};
26
+ this.modelClassName = null;
27
+ this.perspective = perspective;
28
+ this.ctor = ctor;
29
+ if (query)
30
+ this.queryParams = query;
31
+ }
32
+ /**
33
+ * Disposes of the current live subscription (if any).
34
+ * Call when done to avoid memory leaks.
35
+ */
36
+ dispose() {
37
+ if (this.currentSubscription) {
38
+ this.currentSubscription.dispose();
39
+ this.currentSubscription = undefined;
40
+ }
41
+ }
42
+ where(conditions) {
43
+ this.queryParams.where = conditions;
44
+ return this;
45
+ }
46
+ order(orderBy) {
47
+ this.queryParams.order = orderBy;
48
+ return this;
49
+ }
50
+ limit(limit) {
51
+ this.queryParams.limit = limit;
52
+ return this;
53
+ }
54
+ offset(offset) {
55
+ this.queryParams.offset = offset;
56
+ return this;
57
+ }
58
+ properties(properties) {
59
+ this.queryParams.properties = properties;
60
+ return this;
61
+ }
62
+ /**
63
+ * Eagerly load specific relations as full model instances.
64
+ *
65
+ * Key = relation field name on the model.
66
+ * Value = `true` (all instances) or a `Query` to filter/order/limit the nested set.
67
+ *
68
+ * @example
69
+ * ```typescript
70
+ * Recipe.query(perspective)
71
+ * .include({
72
+ * comments: true,
73
+ * tags: { where: { active: true }, limit: 5 },
74
+ * })
75
+ * .get();
76
+ * ```
77
+ */
78
+ include(map) {
79
+ this.queryParams.include = map;
80
+ return this;
81
+ }
82
+ overrideModelClassName(className) {
83
+ this.modelClassName = className;
84
+ return this;
85
+ }
86
+ /**
87
+ * Executes the query once and returns the results.
88
+ */
89
+ async get() {
90
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
91
+ const result = await this.perspective.querySurrealDB(surrealQuery);
92
+ const { results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
93
+ return results;
94
+ }
95
+ /**
96
+ * Subscribes to live updates and returns initial results.
97
+ * Call `dispose()` when done.
98
+ */
99
+ async subscribe(callback) {
100
+ this.dispose();
101
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
102
+ this.currentSubscription =
103
+ await this.perspective.subscribeSurrealDB(surrealQuery);
104
+ const processResults = async (result) => {
105
+ const { results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
106
+ callback(results);
107
+ };
108
+ this.currentSubscription.onResult(processResults);
109
+ const { results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, this.currentSubscription.result);
110
+ return results;
111
+ }
112
+ /** Returns the total count of matching entities. */
113
+ async count() {
114
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
115
+ const result = await this.perspective.querySurrealDB(surrealQuery);
116
+ const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
117
+ return totalCount;
118
+ }
119
+ /**
120
+ * Subscribes to count updates. Call `dispose()` when done.
121
+ */
122
+ async countSubscribe(callback) {
123
+ this.dispose();
124
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
125
+ this.currentSubscription =
126
+ await this.perspective.subscribeSurrealDB(surrealQuery);
127
+ const processResults = async (result) => {
128
+ const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
129
+ callback(totalCount);
130
+ };
131
+ this.currentSubscription.onResult(processResults);
132
+ const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, this.currentSubscription.result);
133
+ return totalCount;
134
+ }
135
+ /** Returns a single page of results with pagination metadata. */
136
+ async paginate(pageSize, pageNumber) {
137
+ const paginationQuery = {
138
+ ...this.queryParams,
139
+ limit: pageSize,
140
+ offset: pageSize * (pageNumber - 1),
141
+ count: true,
142
+ };
143
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, paginationQuery);
144
+ const result = await this.perspective.querySurrealDB(surrealQuery);
145
+ const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result));
146
+ return { results, totalCount, pageSize, pageNumber };
147
+ }
148
+ /**
149
+ * Subscribes to paginated live updates. Call `dispose()` when done.
150
+ */
151
+ async paginateSubscribe(pageSize, pageNumber, callback) {
152
+ this.dispose();
153
+ const paginationQuery = {
154
+ ...this.queryParams,
155
+ limit: pageSize,
156
+ offset: pageSize * (pageNumber - 1),
157
+ count: true,
158
+ };
159
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, paginationQuery);
160
+ this.currentSubscription =
161
+ await this.perspective.subscribeSurrealDB(surrealQuery);
162
+ const processResults = async (result) => {
163
+ const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result));
164
+ callback({ results, totalCount, pageSize, pageNumber });
165
+ };
166
+ this.currentSubscription.onResult(processResults);
167
+ const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, this.currentSubscription.result));
168
+ return { results, totalCount, pageSize, pageNumber };
169
+ }
170
+ /**
171
+ * Terminal: creates a live subscription using the query parameters accumulated
172
+ * so far. Fires `callback` immediately with current results, then on every
173
+ * relevant link change.
174
+ *
175
+ * Pass additional delivery options (`debounce`, `onError`) in `deliveryOpts`.
176
+ * Call `sub.unsubscribe()` to detach.
177
+ *
178
+ * @example
179
+ * ```typescript
180
+ * const sub = Post.query(perspective)
181
+ * .where({ published: true })
182
+ * .order({ createdAt: "DESC" })
183
+ * .live((posts) => setPosts(posts), { debounce: 300 });
184
+ *
185
+ * // cleanup:
186
+ * sub.unsubscribe();
187
+ * ```
188
+ */
189
+ live(callback, deliveryOpts) {
190
+ const options = { ...this.queryParams, ...deliveryOpts };
191
+ return createSubscription((p, q) => this.ctor.findAll(p, q ?? {}), () => this.ctor.getModelMetadata(), this.perspective, options, callback);
192
+ }
193
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Pure SurrealQL query-building functions for the AD4M model layer.
3
+ *
4
+ * All functions are stateless — they take `ModelMetadata` (and optionally a
5
+ * `Query`) as plain data and return strings or booleans. No dependency on the
6
+ * `Ad4mModel` class, which means they can be imported by tests and other
7
+ * modules without pulling in the full class graph.
8
+ *
9
+ * `Ad4mModel` keeps thin static wrapper methods with the original signatures so
10
+ * the public API is unchanged.
11
+ */
12
+ import { ModelMetadata, Query, Where, WhereCondition } from "../types";
13
+ /**
14
+ * Formats a value for use in SurrealQL queries.
15
+ *
16
+ * - Strings: wrapped in single quotes, special characters escaped
17
+ * - Numbers / booleans: converted to string
18
+ * - Arrays: recursively formatted, wrapped in `[...]`
19
+ */
20
+ export declare function formatSurrealValue(value: any): string;
21
+ /**
22
+ * Builds graph-traversal WHERE clause filters (`->link[WHERE ...]`).
23
+ * Used by `buildSurrealQuery` — more efficient than subqueries because
24
+ * SurrealDB can use graph indexes.
25
+ */
26
+ export declare function buildGraphTraversalWhereClause(metadata: ModelMetadata, where?: Where): string;
27
+ /**
28
+ * Builds a legacy subquery-based WHERE clause.
29
+ * Kept for compatibility; prefer `buildGraphTraversalWhereClause`.
30
+ */
31
+ export declare function buildSurrealWhereClause(metadata: ModelMetadata, where?: Where): string;
32
+ export declare function buildSurrealSelectFields(metadata: ModelMetadata, properties?: string[], relations?: string[]): string;
33
+ export declare function buildSurrealSelectFieldsWithAggregation(metadata: ModelMetadata, properties?: string[], relations?: string[]): string;
34
+ /**
35
+ * Builds the SurrealQL SELECT query for a given model metadata + query params.
36
+ * This is the extracted, pure-function form of `Ad4mModel.queryToSurrealQL`.
37
+ */
38
+ export declare function buildSurrealQuery(metadata: ModelMetadata, query: Query): string;
39
+ /**
40
+ * Builds a count query (same as `buildSurrealQuery` but without LIMIT/OFFSET).
41
+ */
42
+ export declare function buildSurrealCountQuery(metadata: ModelMetadata, query: Query): string;
43
+ /**
44
+ * Checks whether a single value satisfies a WhereCondition.
45
+ * Used for post-query JavaScript filtering of operators that SurrealDB
46
+ * cannot evaluate reliably (gt/gte/lt/lte/between/contains on literals).
47
+ */
48
+ export declare function matchesCondition(value: any, condition: WhereCondition): boolean;