@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.
- package/lib/index.cjs +1392 -777
- package/lib/index.js +1376 -775
- package/lib/src/Literal.js +6 -5
- package/lib/src/agent/AgentClient.d.ts +5 -1
- package/lib/src/agent/AgentClient.js +48 -2
- package/lib/src/expression/ExpressionRef.js +2 -2
- package/lib/src/language/Language.d.ts +41 -3
- package/lib/src/model/Ad4mModel.d.ts +28 -28
- package/lib/src/model/Ad4mModel.js +129 -101
- package/lib/src/model/Ad4mModel.test.js +1543 -535
- package/lib/src/model/ModelQueryBuilder.d.ts +48 -34
- package/lib/src/model/ModelQueryBuilder.js +163 -78
- package/lib/src/model/Subject.js +6 -6
- package/lib/src/model/decorators.d.ts +14 -8
- package/lib/src/model/decorators.js +41 -14
- package/lib/src/model/hydration-batch.d.ts +34 -0
- package/lib/src/model/hydration-batch.js +147 -0
- package/lib/src/model/hydration.d.ts +3 -3
- package/lib/src/model/hydration.js +106 -36
- package/lib/src/model/index.d.ts +4 -1
- package/lib/src/model/index.js +4 -1
- package/lib/src/model/json-schema.js +2 -2
- package/lib/src/model/query-cache.d.ts +30 -0
- package/lib/src/model/query-cache.js +66 -0
- package/lib/src/model/query-cache.test.d.ts +1 -0
- package/lib/src/model/query-cache.test.js +43 -0
- package/lib/src/model/query-common.d.ts +1 -1
- package/lib/src/model/query-common.js +1 -1
- package/lib/src/model/query-sparql-batch.d.ts +17 -0
- package/lib/src/model/query-sparql-batch.js +260 -0
- package/lib/src/model/query-sparql.d.ts +47 -0
- package/lib/src/model/query-sparql.js +336 -0
- package/lib/src/model/query-utils.d.ts +45 -0
- package/lib/src/model/query-utils.js +140 -0
- package/lib/src/model/relation-filtering.test.js +15 -15
- package/lib/src/model/sdna.js +1 -1
- package/lib/src/model/shacl-gen.js +42 -18
- package/lib/src/model/subscription-pool.d.ts +39 -0
- package/lib/src/model/subscription-pool.js +119 -0
- package/lib/src/model/types.d.ts +3 -3
- package/lib/src/model/types.js +1 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +1 -17
- package/lib/src/perspectives/PerspectiveClient.js +5 -57
- package/lib/src/perspectives/PerspectiveProxy.d.ts +51 -30
- package/lib/src/perspectives/PerspectiveProxy.js +224 -177
- package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveResolver.js +0 -11
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
- package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
- package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
- package/lib/src/runtime/RuntimeResolver.js +56 -0
- package/lib/src/schema.gql +11 -1
- package/lib/src/shacl/SHACLFlow.d.ts +1 -1
- package/lib/src/shacl/SHACLFlow.js +9 -9
- package/lib/src/shacl/SHACLShape.d.ts +1 -1
- package/lib/src/shacl/SHACLShape.js +38 -38
- package/lib/src/typeDefs.js +11 -1
- package/lib/src/utils.d.ts +6 -6
- package/lib/src/utils.js +6 -6
- package/package.json +1 -1
- package/src/Literal.test.ts +10 -5
- package/src/Literal.ts +6 -5
- package/src/agent/AgentClient.ts +53 -1
- package/src/expression/ExpressionRef.ts +2 -2
- package/src/language/Language.ts +48 -3
- package/src/model/Ad4mModel.test.ts +1515 -565
- package/src/model/Ad4mModel.ts +142 -102
- package/src/model/ModelQueryBuilder.ts +185 -86
- package/src/model/Subject.ts +6 -6
- package/src/model/decorators.ts +51 -22
- package/src/model/hydration-batch.ts +205 -0
- package/src/model/hydration.ts +102 -39
- package/src/model/index.ts +4 -1
- package/src/model/json-schema.ts +2 -2
- package/src/model/query-cache.test.ts +54 -0
- package/src/model/query-cache.ts +79 -0
- package/src/model/query-common.ts +1 -1
- package/src/model/query-sparql-batch.ts +301 -0
- package/src/model/query-sparql.ts +363 -0
- package/src/model/{surreal-utils.ts → query-utils.ts} +40 -27
- package/src/model/relation-filtering.test.ts +15 -15
- package/src/model/sdna.ts +1 -1
- package/src/model/shacl-gen.ts +42 -17
- package/src/model/subscription-pool.ts +163 -0
- package/src/model/types.ts +3 -3
- package/src/perspectives/PerspectiveClient.ts +5 -61
- package/src/perspectives/PerspectiveProxy.ts +226 -181
- package/src/perspectives/PerspectiveResolver.ts +0 -8
- package/src/perspectives/WakerSubscriptionManager.ts +8 -9
- package/src/runtime/RuntimeResolver.ts +43 -0
- package/src/shacl/SHACLFlow.ts +9 -9
- package/src/shacl/SHACLShape.ts +39 -39
- package/src/utils.ts +6 -6
- package/src/model/query-surreal.ts +0 -280
|
@@ -7,8 +7,8 @@
|
|
|
7
7
|
* decorators.ts stays focused on decorator registration logic.
|
|
8
8
|
*/
|
|
9
9
|
import { SHACLShape } from "../shacl/SHACLShape";
|
|
10
|
-
import {
|
|
11
|
-
import { compileWhereClause } from "./
|
|
10
|
+
import { escapeQueryString } from "../utils";
|
|
11
|
+
import { compileWhereClause } from "./query-utils";
|
|
12
12
|
import { propertyNameToSetterName } from "./util";
|
|
13
13
|
/**
|
|
14
14
|
* Build a SHACL shape for a model class.
|
|
@@ -131,7 +131,7 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
|
|
|
131
131
|
// ── Constructor / Destructor entries ────────────────────────────
|
|
132
132
|
const effectiveInitial = propMeta.initial
|
|
133
133
|
?? (propMeta.required && propMeta.writable && !propMeta.flag && propMeta.through
|
|
134
|
-
? "literal
|
|
134
|
+
? "literal:string:" : undefined);
|
|
135
135
|
if (effectiveInitial) {
|
|
136
136
|
constructorActions.push({
|
|
137
137
|
action: "addLink",
|
|
@@ -182,7 +182,7 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
|
|
|
182
182
|
// ── Build Getter (conformance filter) ───────────────────────────
|
|
183
183
|
// Priority chain:
|
|
184
184
|
// 1. Explicit getter string → use verbatim
|
|
185
|
-
// 2. `where` clause → compile DSL to
|
|
185
|
+
// 2. `where` clause → compile DSL to SPARQL getter
|
|
186
186
|
// 3. target + filter !== false → auto-derive from shape
|
|
187
187
|
if (relMeta.getter) {
|
|
188
188
|
relShape.getter = relMeta.getter;
|
|
@@ -195,8 +195,8 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
|
|
|
195
195
|
: null;
|
|
196
196
|
const conditions = compileWhereClause(relMeta.where, targetMetadata);
|
|
197
197
|
if (conditions.length > 0) {
|
|
198
|
-
const escapedPredicate =
|
|
199
|
-
relShape.getter = `
|
|
198
|
+
const escapedPredicate = escapeQueryString(relMeta.predicate);
|
|
199
|
+
relShape.getter = `SELECT ?target WHERE { <Base> <${escapedPredicate}> ?target . ${conditions.join(' ')} }`;
|
|
200
200
|
}
|
|
201
201
|
}
|
|
202
202
|
catch (e) {
|
|
@@ -204,18 +204,42 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
|
|
|
204
204
|
}
|
|
205
205
|
}
|
|
206
206
|
else if (relMeta.target && relMeta.filter !== false) {
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
207
|
+
// Lazy conformance filter: store deferred reference,
|
|
208
|
+
// resolve on first access via a getter on relShape
|
|
209
|
+
const targetThunk = relMeta.target;
|
|
210
|
+
const predicate = relMeta.predicate;
|
|
211
|
+
let resolved = false;
|
|
212
|
+
let cachedGetter;
|
|
213
|
+
let cachedConditions;
|
|
214
|
+
const resolveFilter = () => {
|
|
215
|
+
if (resolved)
|
|
216
|
+
return;
|
|
217
|
+
resolved = true;
|
|
218
|
+
try {
|
|
219
|
+
const TargetClass = targetThunk();
|
|
220
|
+
const filter = conformanceFilterFn(predicate, TargetClass);
|
|
221
|
+
if (filter) {
|
|
222
|
+
cachedGetter = filter.getter;
|
|
223
|
+
cachedConditions = filter.conformanceConditions;
|
|
224
|
+
}
|
|
213
225
|
}
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
226
|
+
catch (e) {
|
|
227
|
+
// Target class may not be available yet
|
|
228
|
+
}
|
|
229
|
+
};
|
|
230
|
+
// Define lazy getters that resolve on first access
|
|
231
|
+
Object.defineProperty(relShape, 'getter', {
|
|
232
|
+
get() { resolveFilter(); return cachedGetter; },
|
|
233
|
+
set(v) { resolved = true; cachedGetter = v; },
|
|
234
|
+
enumerable: true,
|
|
235
|
+
configurable: true,
|
|
236
|
+
});
|
|
237
|
+
Object.defineProperty(relShape, 'conformanceConditions', {
|
|
238
|
+
get() { resolveFilter(); return cachedConditions; },
|
|
239
|
+
set(v) { resolved = true; cachedConditions = v; },
|
|
240
|
+
enumerable: true,
|
|
241
|
+
configurable: true,
|
|
242
|
+
});
|
|
219
243
|
}
|
|
220
244
|
// ── sh:class — target shape reference ───────────────────────────
|
|
221
245
|
if (relMeta.target) {
|
|
@@ -233,7 +257,7 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
|
|
|
233
257
|
shape.addProperty(relShape);
|
|
234
258
|
}
|
|
235
259
|
// Always set constructor and destructor actions on the shape, even
|
|
236
|
-
// when empty. An empty array serialises to `literal
|
|
260
|
+
// when empty. An empty array serialises to `literal:string:[]`
|
|
237
261
|
// which the Rust executor parses as a valid (no-op) command list,
|
|
238
262
|
// avoiding "No SHACL constructor found" errors for models whose
|
|
239
263
|
// properties are all optional and have no @Flag.
|
|
@@ -0,0 +1,39 @@
|
|
|
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
|
+
import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
12
|
+
type HydrateCallback = (rawResult: any) => Promise<any>;
|
|
13
|
+
type ResultCallback = (hydratedResult: any) => void;
|
|
14
|
+
export interface PooledSubscription {
|
|
15
|
+
/** The initial (hydrated) result */
|
|
16
|
+
initialResult: any;
|
|
17
|
+
/** Unsubscribe this particular callback from the pool */
|
|
18
|
+
dispose: () => void;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Subscribe to a SPARQL query, sharing the underlying subscription
|
|
22
|
+
* with any other subscribers using the same perspective + query.
|
|
23
|
+
*
|
|
24
|
+
* @param perspective - The perspective proxy
|
|
25
|
+
* @param sparqlQuery - The SPARQL query text
|
|
26
|
+
* @param hydrate - Async function that takes raw SPARQL results and returns hydrated results
|
|
27
|
+
* @param onResult - Callback for subsequent result updates (hydrated)
|
|
28
|
+
* @returns PooledSubscription with initial result and dispose function
|
|
29
|
+
*/
|
|
30
|
+
export declare function pooledSubscribe(perspective: PerspectiveProxy, sparqlQuery: string, hydrate: HydrateCallback, onResult: ResultCallback): Promise<PooledSubscription>;
|
|
31
|
+
/**
|
|
32
|
+
* Clear the entire pool (for testing).
|
|
33
|
+
*/
|
|
34
|
+
export declare function clearSubscriptionPool(): void;
|
|
35
|
+
/**
|
|
36
|
+
* Get the current pool size (for testing).
|
|
37
|
+
*/
|
|
38
|
+
export declare function subscriptionPoolSize(): number;
|
|
39
|
+
export {};
|
|
@@ -0,0 +1,119 @@
|
|
|
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
|
+
const pool = new Map();
|
|
12
|
+
function makeKey(perspectiveUUID, sparqlQuery) {
|
|
13
|
+
return `${perspectiveUUID}::${sparqlQuery}`;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Subscribe to a SPARQL query, sharing the underlying subscription
|
|
17
|
+
* with any other subscribers using the same perspective + query.
|
|
18
|
+
*
|
|
19
|
+
* @param perspective - The perspective proxy
|
|
20
|
+
* @param sparqlQuery - The SPARQL query text
|
|
21
|
+
* @param hydrate - Async function that takes raw SPARQL results and returns hydrated results
|
|
22
|
+
* @param onResult - Callback for subsequent result updates (hydrated)
|
|
23
|
+
* @returns PooledSubscription with initial result and dispose function
|
|
24
|
+
*/
|
|
25
|
+
export async function pooledSubscribe(perspective, sparqlQuery, hydrate, onResult) {
|
|
26
|
+
const uuid = perspective.uuid || perspective.handle?.uuid || '';
|
|
27
|
+
const key = makeKey(uuid, sparqlQuery);
|
|
28
|
+
const entry = pool.get(key);
|
|
29
|
+
const subscriber = { onResult, hydrate };
|
|
30
|
+
if (entry) {
|
|
31
|
+
// Join existing subscription
|
|
32
|
+
entry.callbacks.add(subscriber);
|
|
33
|
+
entry.refCount++;
|
|
34
|
+
// Hydrate latest result for this new subscriber
|
|
35
|
+
let initialResult;
|
|
36
|
+
if (entry.latestHydrated !== undefined) {
|
|
37
|
+
initialResult = entry.latestHydrated;
|
|
38
|
+
}
|
|
39
|
+
else if (entry.latestRaw !== undefined) {
|
|
40
|
+
initialResult = await hydrate(entry.latestRaw);
|
|
41
|
+
}
|
|
42
|
+
return {
|
|
43
|
+
initialResult,
|
|
44
|
+
dispose: () => disposeSubscriber(key, subscriber),
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
// Create new subscription
|
|
48
|
+
const subscription = await perspective.subscribeQuery(sparqlQuery);
|
|
49
|
+
const newEntry = {
|
|
50
|
+
subscription,
|
|
51
|
+
callbacks: new Set([subscriber]),
|
|
52
|
+
latestRaw: subscription.result,
|
|
53
|
+
latestHydrated: undefined,
|
|
54
|
+
hydrating: false,
|
|
55
|
+
refCount: 1,
|
|
56
|
+
};
|
|
57
|
+
pool.set(key, newEntry);
|
|
58
|
+
// Set up shared result handler
|
|
59
|
+
subscription.onResult(async (rawResult) => {
|
|
60
|
+
newEntry.latestRaw = rawResult;
|
|
61
|
+
newEntry.hydrating = true;
|
|
62
|
+
try {
|
|
63
|
+
// Hydrate ONCE using the first subscriber's hydrate function
|
|
64
|
+
const firstSub = newEntry.callbacks.values().next().value;
|
|
65
|
+
if (firstSub) {
|
|
66
|
+
const hydrated = await firstSub.hydrate(rawResult);
|
|
67
|
+
newEntry.latestHydrated = hydrated;
|
|
68
|
+
// Distribute to all callbacks
|
|
69
|
+
for (const cb of newEntry.callbacks) {
|
|
70
|
+
try {
|
|
71
|
+
cb.onResult(hydrated);
|
|
72
|
+
}
|
|
73
|
+
catch (e) { /* subscriber error */ }
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
finally {
|
|
78
|
+
newEntry.hydrating = false;
|
|
79
|
+
}
|
|
80
|
+
});
|
|
81
|
+
// Hydrate initial result
|
|
82
|
+
const initialResult = await hydrate(subscription.result);
|
|
83
|
+
newEntry.latestHydrated = initialResult;
|
|
84
|
+
return {
|
|
85
|
+
initialResult,
|
|
86
|
+
dispose: () => disposeSubscriber(key, subscriber),
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
function disposeSubscriber(key, subscriber) {
|
|
90
|
+
const entry = pool.get(key);
|
|
91
|
+
if (!entry)
|
|
92
|
+
return;
|
|
93
|
+
entry.callbacks.delete(subscriber);
|
|
94
|
+
entry.refCount--;
|
|
95
|
+
if (entry.refCount <= 0) {
|
|
96
|
+
// Last subscriber — tear down the underlying subscription
|
|
97
|
+
if (entry.subscription?.dispose) {
|
|
98
|
+
entry.subscription.dispose();
|
|
99
|
+
}
|
|
100
|
+
pool.delete(key);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Clear the entire pool (for testing).
|
|
105
|
+
*/
|
|
106
|
+
export function clearSubscriptionPool() {
|
|
107
|
+
for (const entry of pool.values()) {
|
|
108
|
+
if (entry.subscription?.dispose) {
|
|
109
|
+
entry.subscription.dispose();
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
pool.clear();
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Get the current pool size (for testing).
|
|
116
|
+
*/
|
|
117
|
+
export function subscriptionPoolSize() {
|
|
118
|
+
return pool.size;
|
|
119
|
+
}
|
package/lib/src/model/types.d.ts
CHANGED
|
@@ -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
|
-
* (`
|
|
5
|
+
* (`query-utils.ts`, `decorators.ts`, etc.) can import types without
|
|
6
6
|
* creating circular runtime dependencies on `Ad4mModel.ts`.
|
|
7
7
|
*/
|
|
8
8
|
import type { Ad4mModel } from "./Ad4mModel";
|
|
@@ -128,7 +128,7 @@ export interface PropertyMetadata {
|
|
|
128
128
|
prologGetter?: string;
|
|
129
129
|
/** Custom Prolog setter code */
|
|
130
130
|
prologSetter?: string;
|
|
131
|
-
/** Custom
|
|
131
|
+
/** Custom getter code */
|
|
132
132
|
getter?: string;
|
|
133
133
|
/** Whether stored locally only */
|
|
134
134
|
local?: boolean;
|
|
@@ -145,7 +145,7 @@ export interface RelationMetadata {
|
|
|
145
145
|
name: string;
|
|
146
146
|
/** The predicate URI (through value) */
|
|
147
147
|
predicate: string;
|
|
148
|
-
/** Custom
|
|
148
|
+
/** Custom getter code */
|
|
149
149
|
getter?: string;
|
|
150
150
|
/** Whether stored locally only */
|
|
151
151
|
local?: boolean;
|
package/lib/src/model/types.js
CHANGED
|
@@ -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
|
-
* (`
|
|
5
|
+
* (`query-utils.ts`, `decorators.ts`, etc.) can import types without
|
|
6
6
|
* creating circular runtime dependencies on `Ad4mModel.ts`.
|
|
7
7
|
*/
|
|
8
8
|
export {};
|
|
@@ -27,28 +27,12 @@ export declare class PerspectiveClient {
|
|
|
27
27
|
publishSnapshotByUUID(uuid: string): Promise<string | null>;
|
|
28
28
|
queryLinks(uuid: string, query: LinkQuery): Promise<LinkExpression[]>;
|
|
29
29
|
queryProlog(uuid: string, query: string): Promise<any>;
|
|
30
|
-
|
|
31
|
-
* Executes a read-only SurrealQL query against a perspective's link cache.
|
|
32
|
-
*
|
|
33
|
-
* Security: Only SELECT, RETURN, and other read-only queries are permitted.
|
|
34
|
-
* Mutating operations (DELETE, UPDATE, INSERT, etc.) are blocked.
|
|
35
|
-
*
|
|
36
|
-
* Note: GraphQL field name is "perspectiveQuerySurrealDb" (lowercase "b" in "Db")
|
|
37
|
-
* as generated from Rust method "perspective_query_surreal_db"
|
|
38
|
-
*/
|
|
39
|
-
querySurrealDB(uuid: string, query: string): Promise<any>;
|
|
30
|
+
querySparql(uuid: string, query: string): Promise<any>;
|
|
40
31
|
subscribeQuery(uuid: string, query: string): Promise<{
|
|
41
32
|
subscriptionId: string;
|
|
42
33
|
result: AllInstancesResult;
|
|
43
34
|
isInit?: boolean;
|
|
44
35
|
}>;
|
|
45
|
-
perspectiveSubscribeSurrealQuery(uuid: string, query: string): Promise<{
|
|
46
|
-
subscriptionId: string;
|
|
47
|
-
result: AllInstancesResult;
|
|
48
|
-
isInit?: boolean;
|
|
49
|
-
}>;
|
|
50
|
-
perspectiveKeepAliveSurrealQuery(uuid: string, subscriptionId: string): Promise<boolean>;
|
|
51
|
-
perspectiveDisposeSurrealQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean>;
|
|
52
36
|
subscribeToQueryUpdates(subscriptionId: string, onData: (result: AllInstancesResult) => void): () => void;
|
|
53
37
|
keepAliveQuery(uuid: string, subscriptionId: string): Promise<boolean>;
|
|
54
38
|
disposeQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean>;
|
|
@@ -139,23 +139,14 @@ export class PerspectiveClient {
|
|
|
139
139
|
}));
|
|
140
140
|
return JSON.parse(perspectiveQueryProlog);
|
|
141
141
|
}
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
* Mutating operations (DELETE, UPDATE, INSERT, etc.) are blocked.
|
|
147
|
-
*
|
|
148
|
-
* Note: GraphQL field name is "perspectiveQuerySurrealDb" (lowercase "b" in "Db")
|
|
149
|
-
* as generated from Rust method "perspective_query_surreal_db"
|
|
150
|
-
*/
|
|
151
|
-
async querySurrealDB(uuid, query) {
|
|
152
|
-
const { perspectiveQuerySurrealDb } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").query({
|
|
153
|
-
query: gql `query perspectiveQuerySurrealDb($uuid: String!, $query: String!) {
|
|
154
|
-
perspectiveQuerySurrealDb(uuid: $uuid, query: $query)
|
|
142
|
+
async querySparql(uuid, query) {
|
|
143
|
+
const { perspectiveQuerySparql } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").query({
|
|
144
|
+
query: gql `query perspectiveQuerySparql($uuid: String!, $query: String!) {
|
|
145
|
+
perspectiveQuerySparql(uuid: $uuid, query: $query)
|
|
155
146
|
}`,
|
|
156
147
|
variables: { uuid, query }
|
|
157
148
|
}));
|
|
158
|
-
return JSON.parse(
|
|
149
|
+
return JSON.parse(perspectiveQuerySparql);
|
|
159
150
|
}
|
|
160
151
|
async subscribeQuery(uuid, query) {
|
|
161
152
|
const { perspectiveSubscribeQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
|
|
@@ -182,49 +173,6 @@ export class PerspectiveClient {
|
|
|
182
173
|
}
|
|
183
174
|
return { subscriptionId, result: finalResult, isInit };
|
|
184
175
|
}
|
|
185
|
-
async perspectiveSubscribeSurrealQuery(uuid, query) {
|
|
186
|
-
const { perspectiveSubscribeSurrealQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
|
|
187
|
-
mutation: gql `mutation perspectiveSubscribeSurrealQuery($uuid: String!, $query: String!) {
|
|
188
|
-
perspectiveSubscribeSurrealQuery(uuid: $uuid, query: $query) {
|
|
189
|
-
subscriptionId
|
|
190
|
-
result
|
|
191
|
-
}
|
|
192
|
-
}`,
|
|
193
|
-
variables: { uuid, query }
|
|
194
|
-
}));
|
|
195
|
-
const { subscriptionId, result } = perspectiveSubscribeSurrealQuery;
|
|
196
|
-
let finalResult = result;
|
|
197
|
-
let isInit = false;
|
|
198
|
-
if (finalResult.startsWith("#init#")) {
|
|
199
|
-
finalResult = finalResult.substring(6);
|
|
200
|
-
isInit = true;
|
|
201
|
-
}
|
|
202
|
-
try {
|
|
203
|
-
finalResult = JSON.parse(finalResult);
|
|
204
|
-
}
|
|
205
|
-
catch (e) {
|
|
206
|
-
console.error('Error parsing perspectiveSubscribeSurrealQuery result:', e);
|
|
207
|
-
}
|
|
208
|
-
return { subscriptionId, result: finalResult, isInit };
|
|
209
|
-
}
|
|
210
|
-
async perspectiveKeepAliveSurrealQuery(uuid, subscriptionId) {
|
|
211
|
-
const { perspectiveKeepAliveSurrealQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
|
|
212
|
-
mutation: gql `mutation perspectiveKeepAliveSurrealQuery($uuid: String!, $subscriptionId: String!) {
|
|
213
|
-
perspectiveKeepAliveSurrealQuery(uuid: $uuid, subscriptionId: $subscriptionId)
|
|
214
|
-
}`,
|
|
215
|
-
variables: { uuid, subscriptionId }
|
|
216
|
-
}));
|
|
217
|
-
return perspectiveKeepAliveSurrealQuery;
|
|
218
|
-
}
|
|
219
|
-
async perspectiveDisposeSurrealQuerySubscription(uuid, subscriptionId) {
|
|
220
|
-
const { perspectiveDisposeSurrealQuerySubscription } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
|
|
221
|
-
mutation: gql `mutation perspectiveDisposeSurrealQuerySubscription($uuid: String!, $subscriptionId: String!) {
|
|
222
|
-
perspectiveDisposeSurrealQuerySubscription(uuid: $uuid, subscriptionId: $subscriptionId)
|
|
223
|
-
}`,
|
|
224
|
-
variables: { uuid, subscriptionId }
|
|
225
|
-
}));
|
|
226
|
-
return perspectiveDisposeSurrealQuerySubscription;
|
|
227
|
-
}
|
|
228
176
|
subscribeToQueryUpdates(subscriptionId, onData) {
|
|
229
177
|
const subscription = __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").subscribe({
|
|
230
178
|
query: gql `
|
|
@@ -46,7 +46,6 @@ type QueryCallback = (result: AllInstancesResult) => void;
|
|
|
46
46
|
*/
|
|
47
47
|
export declare class QuerySubscriptionProxy {
|
|
48
48
|
#private;
|
|
49
|
-
isSurrealDB: boolean;
|
|
50
49
|
/** Creates a new query subscription
|
|
51
50
|
* @param uuid - The UUID of the perspective
|
|
52
51
|
* @param query - The Prolog query to subscribe to
|
|
@@ -299,33 +298,22 @@ export declare class PerspectiveProxy {
|
|
|
299
298
|
*/
|
|
300
299
|
infer(query: string): Promise<any>;
|
|
301
300
|
/**
|
|
302
|
-
* Executes a
|
|
303
|
-
* This allows powerful SQL-like queries on the link data stored in
|
|
301
|
+
* Executes a SPARQL query against the perspective's link cache.
|
|
302
|
+
* This allows powerful SQL-like queries on the link data stored in SPARQL.
|
|
304
303
|
*
|
|
305
304
|
* **Security Note:** Only read-only queries (SELECT, RETURN, etc.) are permitted.
|
|
306
305
|
* Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are
|
|
307
306
|
* blocked for security reasons. Use the perspective's add/remove methods to modify links.
|
|
308
307
|
*
|
|
309
|
-
* @param query -
|
|
308
|
+
* @param query - SPARQL query string (read-only operations only)
|
|
310
309
|
* @returns Query results as parsed JSON
|
|
311
310
|
*
|
|
312
|
-
*
|
|
313
|
-
*
|
|
314
|
-
*
|
|
315
|
-
*
|
|
316
|
-
*
|
|
317
|
-
* // Filter links by predicate
|
|
318
|
-
* const follows = await perspective.querySurrealDB(
|
|
319
|
-
* "SELECT * FROM link WHERE predicate = 'follows'"
|
|
320
|
-
* );
|
|
321
|
-
*
|
|
322
|
-
* // Complex aggregation query
|
|
323
|
-
* const stats = await perspective.querySurrealDB(
|
|
324
|
-
* "SELECT predicate, count() as total FROM link GROUP BY predicate"
|
|
325
|
-
* );
|
|
326
|
-
* ```
|
|
311
|
+
* Executes a SPARQL query against the perspective's RDF (Oxigraph) store.
|
|
312
|
+
*
|
|
313
|
+
* @param query - SPARQL query string
|
|
314
|
+
* @returns Query results as parsed JSON
|
|
327
315
|
*/
|
|
328
|
-
|
|
316
|
+
querySparql(query: string): Promise<any>;
|
|
329
317
|
/**
|
|
330
318
|
* Adds a new link to the perspective.
|
|
331
319
|
*
|
|
@@ -552,6 +540,11 @@ export declare class PerspectiveProxy {
|
|
|
552
540
|
* await perspective.addSdna('Recipe', prologCode, 'subject_class');
|
|
553
541
|
*/
|
|
554
542
|
addSdna(name: string, sdnaCode: string, sdnaType: "subject_class" | "flow" | "custom", shaclJson?: string): Promise<boolean>;
|
|
543
|
+
/**
|
|
544
|
+
* Adds a subject class to the perspective.
|
|
545
|
+
* Alias for addSdna() with sdnaType='subject_class'.
|
|
546
|
+
*/
|
|
547
|
+
addSubjectClass(name: string, shaclJson: string): Promise<boolean>;
|
|
555
548
|
/**
|
|
556
549
|
* **Recommended way to add SDNA schemas.**
|
|
557
550
|
*
|
|
@@ -693,6 +686,23 @@ export declare class PerspectiveProxy {
|
|
|
693
686
|
* Gets subject class metadata from SHACL links using SHACLShape.fromLinks().
|
|
694
687
|
* Retrieves the SHACL shape and extracts metadata for instance queries.
|
|
695
688
|
*/
|
|
689
|
+
getSubjectClassMetadata(className: string): Promise<{
|
|
690
|
+
requiredPredicates: string[];
|
|
691
|
+
requiredTriples: Array<{
|
|
692
|
+
predicate: string;
|
|
693
|
+
target?: string;
|
|
694
|
+
}>;
|
|
695
|
+
properties: Map<string, {
|
|
696
|
+
predicate: string;
|
|
697
|
+
resolveLanguage?: string;
|
|
698
|
+
}>;
|
|
699
|
+
relations: Map<string, {
|
|
700
|
+
predicate: string;
|
|
701
|
+
instanceFilter?: string;
|
|
702
|
+
condition?: string;
|
|
703
|
+
}>;
|
|
704
|
+
} | null>;
|
|
705
|
+
/** @deprecated Use getSubjectClassMetadata() */
|
|
696
706
|
getSubjectClassMetadataFromSDNA(className: string): Promise<{
|
|
697
707
|
requiredPredicates: string[];
|
|
698
708
|
requiredTriples: Array<{
|
|
@@ -710,22 +720,26 @@ export declare class PerspectiveProxy {
|
|
|
710
720
|
}>;
|
|
711
721
|
} | null>;
|
|
712
722
|
/**
|
|
713
|
-
* Generates a
|
|
723
|
+
* Generates a SPARQL query to find instances based on class metadata.
|
|
724
|
+
*/
|
|
725
|
+
/**
|
|
726
|
+
* Finds all instances matching subject class metadata by querying links.
|
|
727
|
+
* Returns base URIs of matching instances.
|
|
714
728
|
*/
|
|
715
|
-
private
|
|
729
|
+
private findInstancesByMetadata;
|
|
716
730
|
/**
|
|
717
|
-
* Gets a property value using
|
|
731
|
+
* Gets a property value using SPARQL when Prolog fails.
|
|
718
732
|
* This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
|
|
719
733
|
*/
|
|
720
|
-
|
|
734
|
+
getPropertyValueViaSparql(baseExpression: string, className: string, propertyName: string): Promise<any>;
|
|
721
735
|
/**
|
|
722
|
-
* Gets relation values using
|
|
736
|
+
* Gets relation values using SPARQL when Prolog fails.
|
|
723
737
|
* This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
|
|
724
738
|
* Note: This is used by Subject.ts (legacy pattern). Ad4mModel.ts uses getModelMetadata() instead.
|
|
725
739
|
*/
|
|
726
|
-
|
|
740
|
+
getRelationValuesViaSparql(baseExpression: string, className: string, relationName: string): Promise<any[]>;
|
|
727
741
|
/**
|
|
728
|
-
* Batch-checks multiple expressions against subject class metadata using a single or limited
|
|
742
|
+
* Batch-checks multiple expressions against subject class metadata using a single or limited SPARQL queries.
|
|
729
743
|
* This avoids N+1 query problems by checking all values at once.
|
|
730
744
|
*/
|
|
731
745
|
batchCheckSubjectInstances(expressions: string[], metadata: {
|
|
@@ -785,6 +799,12 @@ export declare class PerspectiveProxy {
|
|
|
785
799
|
* static generateSDNA() function and adds it to the perspective's SDNA.
|
|
786
800
|
*/
|
|
787
801
|
ensureSDNASubjectClass(jsClass: any): Promise<void>;
|
|
802
|
+
/** Takes a JS class (its constructor) and ensures the SHACL subject class exists. */
|
|
803
|
+
ensureSubjectClass(jsClass: any): Promise<void>;
|
|
804
|
+
/** Clear the per-instance ensured subject class cache.
|
|
805
|
+
* Call this after wiping a perspective's links so that
|
|
806
|
+
* subsequent register() calls re-add SHACL definitions. */
|
|
807
|
+
clearEnsuredSubjectClasses(): void;
|
|
788
808
|
getNeighbourhoodProxy(): NeighbourhoodProxy;
|
|
789
809
|
/**
|
|
790
810
|
* Returns a proxy object for working with AI capabilities.
|
|
@@ -842,7 +862,7 @@ export declare class PerspectiveProxy {
|
|
|
842
862
|
*/
|
|
843
863
|
subscribeInfer(query: string): Promise<QuerySubscriptionProxy>;
|
|
844
864
|
/**
|
|
845
|
-
* Creates a subscription for a
|
|
865
|
+
* Creates a subscription for a SPARQL query that updates in real-time.
|
|
846
866
|
*
|
|
847
867
|
* This method:
|
|
848
868
|
* 1. Creates the subscription on the Rust side
|
|
@@ -857,9 +877,10 @@ export declare class PerspectiveProxy {
|
|
|
857
877
|
* when dispose() is called. Make sure to call dispose() when you're done to
|
|
858
878
|
* prevent memory leaks and ensure proper cleanup of resources.
|
|
859
879
|
*
|
|
860
|
-
|
|
880
|
+
/** Subscribe to a query with live updates via the SPARQL subscription endpoint.
|
|
881
|
+
* @param query - Query string
|
|
861
882
|
* @returns Initialized QuerySubscriptionProxy instance
|
|
862
883
|
*/
|
|
863
|
-
|
|
884
|
+
subscribeQuery(query: string): Promise<QuerySubscriptionProxy>;
|
|
864
885
|
}
|
|
865
886
|
export {};
|