@coasys/ad4m 0.13.0-test-1 → 0.13.0-test-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 (94) hide show
  1. package/lib/index.cjs +1392 -777
  2. package/lib/index.js +1376 -775
  3. package/lib/src/Literal.js +6 -5
  4. package/lib/src/agent/AgentClient.d.ts +5 -1
  5. package/lib/src/agent/AgentClient.js +48 -2
  6. package/lib/src/expression/ExpressionRef.js +2 -2
  7. package/lib/src/language/Language.d.ts +41 -3
  8. package/lib/src/model/Ad4mModel.d.ts +28 -28
  9. package/lib/src/model/Ad4mModel.js +129 -101
  10. package/lib/src/model/Ad4mModel.test.js +1543 -535
  11. package/lib/src/model/ModelQueryBuilder.d.ts +48 -34
  12. package/lib/src/model/ModelQueryBuilder.js +163 -78
  13. package/lib/src/model/Subject.js +6 -6
  14. package/lib/src/model/decorators.d.ts +14 -8
  15. package/lib/src/model/decorators.js +41 -14
  16. package/lib/src/model/hydration-batch.d.ts +34 -0
  17. package/lib/src/model/hydration-batch.js +147 -0
  18. package/lib/src/model/hydration.d.ts +3 -3
  19. package/lib/src/model/hydration.js +106 -36
  20. package/lib/src/model/index.d.ts +4 -1
  21. package/lib/src/model/index.js +4 -1
  22. package/lib/src/model/json-schema.js +2 -2
  23. package/lib/src/model/query-cache.d.ts +30 -0
  24. package/lib/src/model/query-cache.js +66 -0
  25. package/lib/src/model/query-cache.test.d.ts +1 -0
  26. package/lib/src/model/query-cache.test.js +43 -0
  27. package/lib/src/model/query-common.d.ts +1 -1
  28. package/lib/src/model/query-common.js +1 -1
  29. package/lib/src/model/query-sparql-batch.d.ts +17 -0
  30. package/lib/src/model/query-sparql-batch.js +260 -0
  31. package/lib/src/model/query-sparql.d.ts +47 -0
  32. package/lib/src/model/query-sparql.js +336 -0
  33. package/lib/src/model/query-utils.d.ts +45 -0
  34. package/lib/src/model/query-utils.js +140 -0
  35. package/lib/src/model/relation-filtering.test.js +15 -15
  36. package/lib/src/model/sdna.js +1 -1
  37. package/lib/src/model/shacl-gen.js +42 -18
  38. package/lib/src/model/subscription-pool.d.ts +39 -0
  39. package/lib/src/model/subscription-pool.js +119 -0
  40. package/lib/src/model/types.d.ts +3 -3
  41. package/lib/src/model/types.js +1 -1
  42. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -17
  43. package/lib/src/perspectives/PerspectiveClient.js +5 -57
  44. package/lib/src/perspectives/PerspectiveProxy.d.ts +51 -30
  45. package/lib/src/perspectives/PerspectiveProxy.js +224 -177
  46. package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
  47. package/lib/src/perspectives/PerspectiveResolver.js +0 -11
  48. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
  49. package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
  50. package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
  51. package/lib/src/runtime/RuntimeResolver.js +56 -0
  52. package/lib/src/schema.gql +11 -1
  53. package/lib/src/shacl/SHACLFlow.d.ts +1 -1
  54. package/lib/src/shacl/SHACLFlow.js +9 -9
  55. package/lib/src/shacl/SHACLShape.d.ts +1 -1
  56. package/lib/src/shacl/SHACLShape.js +38 -38
  57. package/lib/src/typeDefs.js +11 -1
  58. package/lib/src/utils.d.ts +6 -6
  59. package/lib/src/utils.js +6 -6
  60. package/package.json +1 -1
  61. package/src/Literal.test.ts +10 -5
  62. package/src/Literal.ts +6 -5
  63. package/src/agent/AgentClient.ts +53 -1
  64. package/src/expression/ExpressionRef.ts +2 -2
  65. package/src/language/Language.ts +48 -3
  66. package/src/model/Ad4mModel.test.ts +1515 -565
  67. package/src/model/Ad4mModel.ts +142 -102
  68. package/src/model/ModelQueryBuilder.ts +185 -86
  69. package/src/model/Subject.ts +6 -6
  70. package/src/model/decorators.ts +51 -22
  71. package/src/model/hydration-batch.ts +205 -0
  72. package/src/model/hydration.ts +102 -39
  73. package/src/model/index.ts +4 -1
  74. package/src/model/json-schema.ts +2 -2
  75. package/src/model/query-cache.test.ts +54 -0
  76. package/src/model/query-cache.ts +79 -0
  77. package/src/model/query-common.ts +1 -1
  78. package/src/model/query-sparql-batch.ts +301 -0
  79. package/src/model/query-sparql.ts +363 -0
  80. package/src/model/{surreal-utils.ts → query-utils.ts} +40 -27
  81. package/src/model/relation-filtering.test.ts +15 -15
  82. package/src/model/sdna.ts +1 -1
  83. package/src/model/shacl-gen.ts +42 -17
  84. package/src/model/subscription-pool.ts +163 -0
  85. package/src/model/types.ts +3 -3
  86. package/src/perspectives/PerspectiveClient.ts +5 -61
  87. package/src/perspectives/PerspectiveProxy.ts +226 -181
  88. package/src/perspectives/PerspectiveResolver.ts +0 -8
  89. package/src/perspectives/WakerSubscriptionManager.ts +8 -9
  90. package/src/runtime/RuntimeResolver.ts +43 -0
  91. package/src/shacl/SHACLFlow.ts +9 -9
  92. package/src/shacl/SHACLShape.ts +39 -39
  93. package/src/utils.ts +6 -6
  94. package/src/model/query-surreal.ts +0 -280
@@ -8,8 +8,8 @@
8
8
  */
9
9
  import { SHACLShape } from "../shacl/SHACLShape";
10
10
  import type { SHACLPropertyShape, ConformanceCondition } from "../shacl/SHACLShape";
11
- import { escapeSurrealString } from "../utils";
12
- import { compileWhereClause } from "./surreal-utils";
11
+ import { escapeQueryString } from "../utils";
12
+ import { compileWhereClause } from "./query-utils";
13
13
  import { propertyNameToSetterName } from "./util";
14
14
  import type { PropertyMetadataEntry, RelationMetadataEntry, Ad4mModelLike } from "./decorators";
15
15
 
@@ -163,7 +163,7 @@ export function buildSHACL(
163
163
  // ── Constructor / Destructor entries ────────────────────────────
164
164
  const effectiveInitial = propMeta.initial
165
165
  ?? (propMeta.required && propMeta.writable && !propMeta.flag && propMeta.through
166
- ? "literal://string:" : undefined);
166
+ ? "literal:string:" : undefined);
167
167
 
168
168
  if (effectiveInitial) {
169
169
  constructorActions.push({
@@ -224,7 +224,7 @@ export function buildSHACL(
224
224
  // ── Build Getter (conformance filter) ───────────────────────────
225
225
  // Priority chain:
226
226
  // 1. Explicit getter string → use verbatim
227
- // 2. `where` clause → compile DSL to SurrealQL getter
227
+ // 2. `where` clause → compile DSL to SPARQL getter
228
228
  // 3. target + filter !== false → auto-derive from shape
229
229
  if (relMeta.getter) {
230
230
  relShape.getter = relMeta.getter;
@@ -241,24 +241,49 @@ export function buildSHACL(
241
241
  );
242
242
 
243
243
  if (conditions.length > 0) {
244
- const escapedPredicate = escapeSurrealString(relMeta.predicate);
245
- relShape.getter = `(->link[WHERE predicate = '${escapedPredicate}'].out[WHERE ${conditions.join(' AND ')}].uri)`;
244
+ const escapedPredicate = escapeQueryString(relMeta.predicate);
245
+ relShape.getter = `SELECT ?target WHERE { <Base> <${escapedPredicate}> ?target . ${conditions.join(' ')} }`;
246
246
  }
247
247
  } catch (e) {
248
248
  // Target metadata may not be available yet
249
249
  }
250
250
  } else if (relMeta.target && relMeta.filter !== false) {
251
- try {
252
- const TargetClass = relMeta.target();
253
- const filter = conformanceFilterFn(relMeta.predicate, TargetClass);
254
- if (filter) {
255
- relShape.getter = filter.getter;
256
- relShape.conformanceConditions = filter.conformanceConditions;
251
+ // Lazy conformance filter: store deferred reference,
252
+ // resolve on first access via a getter on relShape
253
+ const targetThunk = relMeta.target;
254
+ const predicate = relMeta.predicate;
255
+ let resolved = false;
256
+ let cachedGetter: string | undefined;
257
+ let cachedConditions: ConformanceCondition[] | undefined;
258
+
259
+ const resolveFilter = () => {
260
+ if (resolved) return;
261
+ resolved = true;
262
+ try {
263
+ const TargetClass = targetThunk();
264
+ const filter = conformanceFilterFn(predicate, TargetClass);
265
+ if (filter) {
266
+ cachedGetter = filter.getter;
267
+ cachedConditions = filter.conformanceConditions;
268
+ }
269
+ } catch (e) {
270
+ // Target class may not be available yet
257
271
  }
258
- } catch (e) {
259
- // Target class may not be available yet — getter will be
260
- // absent and runtime will fall back to unfiltered get_links
261
- }
272
+ };
273
+
274
+ // Define lazy getters that resolve on first access
275
+ Object.defineProperty(relShape, 'getter', {
276
+ get() { resolveFilter(); return cachedGetter; },
277
+ set(v: string) { resolved = true; cachedGetter = v; },
278
+ enumerable: true,
279
+ configurable: true,
280
+ });
281
+ Object.defineProperty(relShape, 'conformanceConditions', {
282
+ get() { resolveFilter(); return cachedConditions; },
283
+ set(v: ConformanceCondition[]) { resolved = true; cachedConditions = v; },
284
+ enumerable: true,
285
+ configurable: true,
286
+ });
262
287
  }
263
288
 
264
289
  // ── sh:class — target shape reference ───────────────────────────
@@ -278,7 +303,7 @@ export function buildSHACL(
278
303
  }
279
304
 
280
305
  // Always set constructor and destructor actions on the shape, even
281
- // when empty. An empty array serialises to `literal://string:[]`
306
+ // when empty. An empty array serialises to `literal:string:[]`
282
307
  // which the Rust executor parses as a valid (no-op) command list,
283
308
  // avoiding "No SHACL constructor found" errors for models whose
284
309
  // properties are all optional and have no @Flag.
@@ -0,0 +1,163 @@
1
+ /**
2
+ * Subscription Pool — deduplicates identical SPARQL subscriptions.
3
+ *
4
+ * When multiple UI components subscribe to the same SPARQL query on the same
5
+ * perspective, the pool shares a single `subscribeQuery()` call and distributes
6
+ * results to all registered callbacks. Hydration happens once per result set,
7
+ * then is shared across all subscribers.
8
+ *
9
+ * Key: `perspectiveUUID + sparqlQuery`
10
+ */
11
+
12
+ import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
13
+
14
+ type HydrateCallback = (rawResult: any) => Promise<any>;
15
+ type ResultCallback = (hydratedResult: any) => void;
16
+
17
+ interface PoolEntry {
18
+ /** The underlying subscription from perspective.subscribeQuery() */
19
+ subscription: any;
20
+ /** All registered callbacks */
21
+ callbacks: Set<{ onResult: ResultCallback; hydrate: HydrateCallback }>;
22
+ /** Latest raw result (for new subscribers joining late) */
23
+ latestRaw: any;
24
+ /** Latest hydrated result */
25
+ latestHydrated: any;
26
+ /** Whether hydration is in flight */
27
+ hydrating: boolean;
28
+ /** Reference count for disposal */
29
+ refCount: number;
30
+ }
31
+
32
+ const pool = new Map<string, PoolEntry>();
33
+
34
+ function makeKey(perspectiveUUID: string, sparqlQuery: string): string {
35
+ return `${perspectiveUUID}::${sparqlQuery}`;
36
+ }
37
+
38
+ export interface PooledSubscription {
39
+ /** The initial (hydrated) result */
40
+ initialResult: any;
41
+ /** Unsubscribe this particular callback from the pool */
42
+ dispose: () => void;
43
+ }
44
+
45
+ /**
46
+ * Subscribe to a SPARQL query, sharing the underlying subscription
47
+ * with any other subscribers using the same perspective + query.
48
+ *
49
+ * @param perspective - The perspective proxy
50
+ * @param sparqlQuery - The SPARQL query text
51
+ * @param hydrate - Async function that takes raw SPARQL results and returns hydrated results
52
+ * @param onResult - Callback for subsequent result updates (hydrated)
53
+ * @returns PooledSubscription with initial result and dispose function
54
+ */
55
+ export async function pooledSubscribe(
56
+ perspective: PerspectiveProxy,
57
+ sparqlQuery: string,
58
+ hydrate: HydrateCallback,
59
+ onResult: ResultCallback,
60
+ ): Promise<PooledSubscription> {
61
+ const uuid = (perspective as any).uuid || (perspective as any).handle?.uuid || '';
62
+ const key = makeKey(uuid, sparqlQuery);
63
+
64
+ const entry = pool.get(key);
65
+ const subscriber = { onResult, hydrate };
66
+
67
+ if (entry) {
68
+ // Join existing subscription
69
+ entry.callbacks.add(subscriber);
70
+ entry.refCount++;
71
+
72
+ // Hydrate latest result for this new subscriber
73
+ let initialResult: any;
74
+ if (entry.latestHydrated !== undefined) {
75
+ initialResult = entry.latestHydrated;
76
+ } else if (entry.latestRaw !== undefined) {
77
+ initialResult = await hydrate(entry.latestRaw);
78
+ }
79
+
80
+ return {
81
+ initialResult,
82
+ dispose: () => disposeSubscriber(key, subscriber),
83
+ };
84
+ }
85
+
86
+ // Create new subscription
87
+ const subscription = await perspective.subscribeQuery(sparqlQuery);
88
+
89
+ const newEntry: PoolEntry = {
90
+ subscription,
91
+ callbacks: new Set([subscriber]),
92
+ latestRaw: subscription.result,
93
+ latestHydrated: undefined,
94
+ hydrating: false,
95
+ refCount: 1,
96
+ };
97
+
98
+ pool.set(key, newEntry);
99
+
100
+ // Set up shared result handler
101
+ subscription.onResult(async (rawResult: any) => {
102
+ newEntry.latestRaw = rawResult;
103
+ newEntry.hydrating = true;
104
+ try {
105
+ // Hydrate ONCE using the first subscriber's hydrate function
106
+ const firstSub = newEntry.callbacks.values().next().value;
107
+ if (firstSub) {
108
+ const hydrated = await firstSub.hydrate(rawResult);
109
+ newEntry.latestHydrated = hydrated;
110
+ // Distribute to all callbacks
111
+ for (const cb of newEntry.callbacks) {
112
+ try { cb.onResult(hydrated); } catch (e) { /* subscriber error */ }
113
+ }
114
+ }
115
+ } finally {
116
+ newEntry.hydrating = false;
117
+ }
118
+ });
119
+
120
+ // Hydrate initial result
121
+ const initialResult = await hydrate(subscription.result);
122
+ newEntry.latestHydrated = initialResult;
123
+
124
+ return {
125
+ initialResult,
126
+ dispose: () => disposeSubscriber(key, subscriber),
127
+ };
128
+ }
129
+
130
+ function disposeSubscriber(key: string, subscriber: { onResult: ResultCallback; hydrate: HydrateCallback }): void {
131
+ const entry = pool.get(key);
132
+ if (!entry) return;
133
+
134
+ entry.callbacks.delete(subscriber);
135
+ entry.refCount--;
136
+
137
+ if (entry.refCount <= 0) {
138
+ // Last subscriber — tear down the underlying subscription
139
+ if (entry.subscription?.dispose) {
140
+ entry.subscription.dispose();
141
+ }
142
+ pool.delete(key);
143
+ }
144
+ }
145
+
146
+ /**
147
+ * Clear the entire pool (for testing).
148
+ */
149
+ export function clearSubscriptionPool(): void {
150
+ for (const entry of pool.values()) {
151
+ if (entry.subscription?.dispose) {
152
+ entry.subscription.dispose();
153
+ }
154
+ }
155
+ pool.clear();
156
+ }
157
+
158
+ /**
159
+ * Get the current pool size (for testing).
160
+ */
161
+ export function subscriptionPoolSize(): number {
162
+ return pool.size;
163
+ }
@@ -2,7 +2,7 @@
2
2
  * Shared type definitions for the Ad4mModel system.
3
3
  *
4
4
  * Extracted into a standalone module so that utility files
5
- * (`surreal-utils.ts`, `decorators.ts`, etc.) can import types without
5
+ * (`query-utils.ts`, `decorators.ts`, etc.) can import types without
6
6
  * creating circular runtime dependencies on `Ad4mModel.ts`.
7
7
  */
8
8
 
@@ -134,7 +134,7 @@ export interface PropertyMetadata {
134
134
  prologGetter?: string;
135
135
  /** Custom Prolog setter code */
136
136
  prologSetter?: string;
137
- /** Custom SurrealQL getter code */
137
+ /** Custom getter code */
138
138
  getter?: string;
139
139
  /** Whether stored locally only */
140
140
  local?: boolean;
@@ -152,7 +152,7 @@ export interface RelationMetadata {
152
152
  name: string;
153
153
  /** The predicate URI (through value) */
154
154
  predicate: string;
155
- /** Custom SurrealQL getter code */
155
+ /** Custom getter code */
156
156
  getter?: string;
157
157
  /** Whether stored locally only */
158
158
  local?: boolean;
@@ -156,24 +156,15 @@ export class PerspectiveClient {
156
156
  return JSON.parse(perspectiveQueryProlog)
157
157
  }
158
158
 
159
- /**
160
- * Executes a read-only SurrealQL query against a perspective's link cache.
161
- *
162
- * Security: Only SELECT, RETURN, and other read-only queries are permitted.
163
- * Mutating operations (DELETE, UPDATE, INSERT, etc.) are blocked.
164
- *
165
- * Note: GraphQL field name is "perspectiveQuerySurrealDb" (lowercase "b" in "Db")
166
- * as generated from Rust method "perspective_query_surreal_db"
167
- */
168
- async querySurrealDB(uuid: string, query: string): Promise<any> {
169
- const { perspectiveQuerySurrealDb } = unwrapApolloResult(await this.#apolloClient.query({
170
- query: gql`query perspectiveQuerySurrealDb($uuid: String!, $query: String!) {
171
- perspectiveQuerySurrealDb(uuid: $uuid, query: $query)
159
+ async querySparql(uuid: string, query: string): Promise<any> {
160
+ const { perspectiveQuerySparql } = unwrapApolloResult(await this.#apolloClient.query({
161
+ query: gql`query perspectiveQuerySparql($uuid: String!, $query: String!) {
162
+ perspectiveQuerySparql(uuid: $uuid, query: $query)
172
163
  }`,
173
164
  variables: { uuid, query }
174
165
  }))
175
166
 
176
- return JSON.parse(perspectiveQuerySurrealDb)
167
+ return JSON.parse(perspectiveQuerySparql)
177
168
  }
178
169
 
179
170
  async subscribeQuery(uuid: string, query: string): Promise<{ subscriptionId: string, result: AllInstancesResult, isInit?: boolean }> {
@@ -201,53 +192,6 @@ export class PerspectiveClient {
201
192
  return { subscriptionId, result: finalResult, isInit }
202
193
  }
203
194
 
204
- async perspectiveSubscribeSurrealQuery(uuid: string, query: string): Promise<{ subscriptionId: string, result: AllInstancesResult, isInit?: boolean }> {
205
- const { perspectiveSubscribeSurrealQuery } = unwrapApolloResult(await this.#apolloClient.mutate({
206
- mutation: gql`mutation perspectiveSubscribeSurrealQuery($uuid: String!, $query: String!) {
207
- perspectiveSubscribeSurrealQuery(uuid: $uuid, query: $query) {
208
- subscriptionId
209
- result
210
- }
211
- }`,
212
- variables: { uuid, query }
213
- }))
214
- const { subscriptionId, result } = perspectiveSubscribeSurrealQuery
215
- let finalResult = result;
216
- let isInit = false;
217
- if(finalResult.startsWith("#init#")) {
218
- finalResult = finalResult.substring(6)
219
- isInit = true;
220
- }
221
- try {
222
- finalResult = JSON.parse(finalResult)
223
- } catch (e) {
224
- console.error('Error parsing perspectiveSubscribeSurrealQuery result:', e)
225
- }
226
- return { subscriptionId, result: finalResult, isInit }
227
- }
228
-
229
- async perspectiveKeepAliveSurrealQuery(uuid: string, subscriptionId: string): Promise<boolean> {
230
- const { perspectiveKeepAliveSurrealQuery } = unwrapApolloResult(await this.#apolloClient.mutate({
231
- mutation: gql`mutation perspectiveKeepAliveSurrealQuery($uuid: String!, $subscriptionId: String!) {
232
- perspectiveKeepAliveSurrealQuery(uuid: $uuid, subscriptionId: $subscriptionId)
233
- }`,
234
- variables: { uuid, subscriptionId }
235
- }))
236
-
237
- return perspectiveKeepAliveSurrealQuery
238
- }
239
-
240
- async perspectiveDisposeSurrealQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean> {
241
- const { perspectiveDisposeSurrealQuerySubscription } = unwrapApolloResult(await this.#apolloClient.mutate({
242
- mutation: gql`mutation perspectiveDisposeSurrealQuerySubscription($uuid: String!, $subscriptionId: String!) {
243
- perspectiveDisposeSurrealQuerySubscription(uuid: $uuid, subscriptionId: $subscriptionId)
244
- }`,
245
- variables: { uuid, subscriptionId }
246
- }))
247
-
248
- return perspectiveDisposeSurrealQuerySubscription
249
- }
250
-
251
195
  subscribeToQueryUpdates(subscriptionId: string, onData: (result: AllInstancesResult) => void): () => void {
252
196
  const subscription = this.#apolloClient.subscribe({
253
197
  query: gql`