@coasys/ad4m 0.11.2-dev.6 → 0.12.0-rc1-dev

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 (36) hide show
  1. package/lib/index.cjs +1737 -314
  2. package/lib/index.js +1736 -315
  3. package/lib/src/index.d.ts +2 -0
  4. package/lib/src/index.js +2 -0
  5. package/lib/src/model/Ad4mModel.js +17 -5
  6. package/lib/src/model/decorators.js +196 -6
  7. package/lib/src/model/util.d.ts +1 -1
  8. package/lib/src/model/util.js +15 -12
  9. package/lib/src/perspectives/PerspectiveClient.d.ts +11 -1
  10. package/lib/src/perspectives/PerspectiveClient.js +15 -4
  11. package/lib/src/perspectives/PerspectiveProxy.d.ts +124 -8
  12. package/lib/src/perspectives/PerspectiveProxy.js +573 -274
  13. package/lib/src/perspectives/PerspectiveResolver.d.ts +1 -1
  14. package/lib/src/perspectives/PerspectiveResolver.js +5 -4
  15. package/lib/src/schema.gql +1 -1
  16. package/lib/src/shacl/SHACLFlow.d.ts +171 -0
  17. package/lib/src/shacl/SHACLFlow.js +370 -0
  18. package/lib/src/shacl/SHACLFlow.test.d.ts +1 -0
  19. package/lib/src/shacl/SHACLFlow.test.js +205 -0
  20. package/lib/src/shacl/SHACLShape.d.ts +108 -0
  21. package/lib/src/shacl/SHACLShape.js +566 -0
  22. package/lib/src/shacl/SHACLShape.test.d.ts +1 -0
  23. package/lib/src/shacl/SHACLShape.test.js +336 -0
  24. package/lib/src/typeDefs.js +1 -1
  25. package/package.json +13 -8
  26. package/src/index.ts +2 -0
  27. package/src/model/Ad4mModel.ts +19 -5
  28. package/src/model/decorators.ts +221 -5
  29. package/src/model/util.ts +15 -12
  30. package/src/perspectives/PerspectiveClient.ts +15 -4
  31. package/src/perspectives/PerspectiveProxy.ts +588 -304
  32. package/src/perspectives/PerspectiveResolver.ts +1 -1
  33. package/src/shacl/SHACLFlow.test.ts +237 -0
  34. package/src/shacl/SHACLFlow.ts +503 -0
  35. package/src/shacl/SHACLShape.test.ts +400 -0
  36. package/src/shacl/SHACLShape.ts +755 -0
@@ -0,0 +1,503 @@
1
+ import { Link } from "../links/Links";
2
+ import { Literal } from "../Literal";
3
+ import { AD4MAction } from "./SHACLShape";
4
+
5
+ // Re-export AD4MAction for consumers who import from SHACLFlow
6
+ export { AD4MAction };
7
+
8
+ /**
9
+ * Link pattern for state detection
10
+ * Used to check if an expression is in a particular state
11
+ */
12
+ export interface LinkPattern {
13
+ /** Optional source pattern (if omitted, uses the expression address) */
14
+ source?: string;
15
+ /** Required predicate to match */
16
+ predicate: string;
17
+ /** Required target value to match */
18
+ target: string;
19
+ }
20
+
21
+ /**
22
+ * Flow State definition
23
+ * Represents a single state in the flow state machine
24
+ */
25
+ export interface FlowState {
26
+ /** State name (e.g., "ready", "doing", "done") */
27
+ name: string;
28
+ /** Numeric state value for ordering (e.g., 0, 0.5, 1) */
29
+ value: number;
30
+ /** Link pattern that indicates this state */
31
+ stateCheck: LinkPattern;
32
+ }
33
+
34
+ /**
35
+ * Flow Transition definition
36
+ * Represents a transition between two states
37
+ */
38
+ export interface FlowTransition {
39
+ /** Name of this action (shown to users, e.g., "Start", "Finish") */
40
+ actionName: string;
41
+ /** State to transition from */
42
+ fromState: string;
43
+ /** State to transition to */
44
+ toState: string;
45
+ /** Actions to execute for this transition */
46
+ actions: AD4MAction[];
47
+ }
48
+
49
+ /**
50
+ * Flowable condition - determines which expressions can enter this flow
51
+ * "any" means all expressions can start this flow
52
+ * Otherwise, a link pattern to check
53
+ */
54
+ export type FlowableCondition = "any" | LinkPattern;
55
+
56
+ /**
57
+ * SHACL Flow - represents a state machine for AD4M expressions
58
+ *
59
+ * Flows define:
60
+ * - Which expressions can enter the flow (flowable condition)
61
+ * - What states exist and how to detect them (via link patterns)
62
+ * - How to transition between states (via actions)
63
+ *
64
+ * @example
65
+ * ```typescript
66
+ * const todoFlow = new SHACLFlow('todo://TODO', 'todo://');
67
+ *
68
+ * // Any expression can become a TODO
69
+ * todoFlow.flowable = 'any';
70
+ *
71
+ * // Define states
72
+ * todoFlow.addState({
73
+ * name: 'ready',
74
+ * value: 0,
75
+ * stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
76
+ * });
77
+ * todoFlow.addState({
78
+ * name: 'doing',
79
+ * value: 0.5,
80
+ * stateCheck: { predicate: 'todo://state', target: 'todo://doing' }
81
+ * });
82
+ * todoFlow.addState({
83
+ * name: 'done',
84
+ * value: 1,
85
+ * stateCheck: { predicate: 'todo://state', target: 'todo://done' }
86
+ * });
87
+ *
88
+ * // Define start action
89
+ * todoFlow.startAction = [{
90
+ * action: 'addLink',
91
+ * source: 'this',
92
+ * predicate: 'todo://state',
93
+ * target: 'todo://ready'
94
+ * }];
95
+ *
96
+ * // Define transitions
97
+ * todoFlow.addTransition({
98
+ * actionName: 'Start',
99
+ * fromState: 'ready',
100
+ * toState: 'doing',
101
+ * actions: [
102
+ * { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://doing' },
103
+ * { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
104
+ * ]
105
+ * });
106
+ *
107
+ * // Store in perspective
108
+ * await perspective.addFlow('TODO', todoFlow);
109
+ * ```
110
+ */
111
+ export class SHACLFlow {
112
+ /** Flow name (e.g., "TODO") */
113
+ public name: string;
114
+
115
+ /** Namespace for generated URIs */
116
+ public namespace: string;
117
+
118
+ /** Condition for which expressions can start this flow */
119
+ public flowable: FlowableCondition = "any";
120
+
121
+ /** Actions to execute when starting the flow */
122
+ public startAction: AD4MAction[] = [];
123
+
124
+ /** States in this flow */
125
+ private _states: FlowState[] = [];
126
+
127
+ /** Transitions between states */
128
+ private _transitions: FlowTransition[] = [];
129
+
130
+ /**
131
+ * Create a new SHACL Flow
132
+ * @param name - Flow name (e.g., "TODO")
133
+ * @param namespace - Namespace for URIs (e.g., "todo://")
134
+ */
135
+ constructor(name: string, namespace: string) {
136
+ this.name = name;
137
+ this.namespace = namespace;
138
+ }
139
+
140
+ /** Get all states */
141
+ get states(): FlowState[] {
142
+ return [...this._states];
143
+ }
144
+
145
+ /** Get all transitions */
146
+ get transitions(): FlowTransition[] {
147
+ return [...this._transitions];
148
+ }
149
+
150
+ /**
151
+ * Add a state to the flow
152
+ * @param state - State definition
153
+ */
154
+ addState(state: FlowState): void {
155
+ this._states.push(state);
156
+ }
157
+
158
+ /**
159
+ * Add a transition to the flow
160
+ * @param transition - Transition definition
161
+ */
162
+ addTransition(transition: FlowTransition): void {
163
+ this._transitions.push(transition);
164
+ }
165
+
166
+ /**
167
+ * Get the flow shape URI
168
+ */
169
+ get flowUri(): string {
170
+ return `${this.namespace}${this.name}Flow`;
171
+ }
172
+
173
+ /**
174
+ * Get a state URI
175
+ */
176
+ stateUri(stateName: string): string {
177
+ return `${this.namespace}${this.name}.${stateName}`;
178
+ }
179
+
180
+ /**
181
+ * Get a transition URI
182
+ */
183
+ transitionUri(fromState: string, toState: string): string {
184
+ return `${this.namespace}${this.name}.${fromState}To${toState}`;
185
+ }
186
+
187
+ /**
188
+ * Serialize the flow to AD4M links
189
+ * These links can be stored in a perspective and queried via SurrealDB
190
+ *
191
+ * @returns Array of Link objects representing the flow
192
+ */
193
+ toLinks(): Link[] {
194
+ const links: Link[] = [];
195
+ const flowUri = this.flowUri;
196
+
197
+ // Flow type
198
+ links.push({
199
+ source: flowUri,
200
+ predicate: "rdf://type",
201
+ target: "ad4m://Flow"
202
+ });
203
+
204
+ // Flow name
205
+ links.push({
206
+ source: flowUri,
207
+ predicate: "ad4m://flowName",
208
+ target: Literal.from(this.name).toUrl()
209
+ });
210
+
211
+ // Flowable condition
212
+ if (this.flowable === "any") {
213
+ links.push({
214
+ source: flowUri,
215
+ predicate: "ad4m://flowable",
216
+ target: "ad4m://any"
217
+ });
218
+ } else {
219
+ links.push({
220
+ source: flowUri,
221
+ predicate: "ad4m://flowable",
222
+ target: `literal://string:${encodeURIComponent(JSON.stringify(this.flowable))}`
223
+ });
224
+ }
225
+
226
+ // Start action
227
+ if (this.startAction.length > 0) {
228
+ links.push({
229
+ source: flowUri,
230
+ predicate: "ad4m://startAction",
231
+ target: `literal://string:${encodeURIComponent(JSON.stringify(this.startAction))}`
232
+ });
233
+ }
234
+
235
+ // States
236
+ for (const state of this._states) {
237
+ const stateUri = this.stateUri(state.name);
238
+
239
+ // Link flow to state
240
+ links.push({
241
+ source: flowUri,
242
+ predicate: "ad4m://hasState",
243
+ target: stateUri
244
+ });
245
+
246
+ // State type
247
+ links.push({
248
+ source: stateUri,
249
+ predicate: "rdf://type",
250
+ target: "ad4m://FlowState"
251
+ });
252
+
253
+ // State name
254
+ links.push({
255
+ source: stateUri,
256
+ predicate: "ad4m://stateName",
257
+ target: Literal.from(state.name).toUrl()
258
+ });
259
+
260
+ // State value
261
+ links.push({
262
+ source: stateUri,
263
+ predicate: "ad4m://stateValue",
264
+ target: Literal.from(state.value).toUrl()
265
+ });
266
+
267
+ // State check pattern
268
+ links.push({
269
+ source: stateUri,
270
+ predicate: "ad4m://stateCheck",
271
+ target: `literal://string:${encodeURIComponent(JSON.stringify(state.stateCheck))}`
272
+ });
273
+ }
274
+
275
+ // Transitions
276
+ for (const transition of this._transitions) {
277
+ const transitionUri = this.transitionUri(transition.fromState, transition.toState);
278
+ const fromStateUri = this.stateUri(transition.fromState);
279
+ const toStateUri = this.stateUri(transition.toState);
280
+
281
+ // Link flow to transition
282
+ links.push({
283
+ source: flowUri,
284
+ predicate: "ad4m://hasTransition",
285
+ target: transitionUri
286
+ });
287
+
288
+ // Transition type
289
+ links.push({
290
+ source: transitionUri,
291
+ predicate: "rdf://type",
292
+ target: "ad4m://FlowTransition"
293
+ });
294
+
295
+ // Action name
296
+ links.push({
297
+ source: transitionUri,
298
+ predicate: "ad4m://actionName",
299
+ target: Literal.from(transition.actionName).toUrl()
300
+ });
301
+
302
+ // From state
303
+ links.push({
304
+ source: transitionUri,
305
+ predicate: "ad4m://fromState",
306
+ target: fromStateUri
307
+ });
308
+
309
+ // To state
310
+ links.push({
311
+ source: transitionUri,
312
+ predicate: "ad4m://toState",
313
+ target: toStateUri
314
+ });
315
+
316
+ // Transition actions
317
+ links.push({
318
+ source: transitionUri,
319
+ predicate: "ad4m://transitionActions",
320
+ target: `literal://string:${encodeURIComponent(JSON.stringify(transition.actions))}`
321
+ });
322
+ }
323
+
324
+ return links;
325
+ }
326
+
327
+ /**
328
+ * Reconstruct a SHACLFlow from links
329
+ *
330
+ * @param links - Array of links containing the flow definition
331
+ * @param flowUri - The URI of the flow to reconstruct
332
+ * @returns Reconstructed SHACLFlow
333
+ */
334
+ static fromLinks(links: Link[], flowUri: string): SHACLFlow {
335
+ // Extract namespace and name from flowUri
336
+ // Format: {namespace}{Name}Flow
337
+ const flowSuffix = "Flow";
338
+ if (!flowUri.endsWith(flowSuffix)) {
339
+ throw new Error(`Invalid flow URI: ${flowUri} (must end with 'Flow')`);
340
+ }
341
+
342
+ const withoutSuffix = flowUri.slice(0, -flowSuffix.length);
343
+ const lastSlashOrColon = Math.max(
344
+ withoutSuffix.lastIndexOf('/'),
345
+ withoutSuffix.lastIndexOf(':')
346
+ );
347
+
348
+ const namespace = withoutSuffix.slice(0, lastSlashOrColon + 1);
349
+ const name = withoutSuffix.slice(lastSlashOrColon + 1);
350
+
351
+ const flow = new SHACLFlow(name, namespace);
352
+
353
+ // Find flowable condition
354
+ const flowableLink = links.find(l =>
355
+ l.source === flowUri && l.predicate === "ad4m://flowable"
356
+ );
357
+ if (flowableLink) {
358
+ if (flowableLink.target === "ad4m://any") {
359
+ flow.flowable = "any";
360
+ } else {
361
+ try {
362
+ const jsonStr = flowableLink.target.replace('literal://string:', '');
363
+ flow.flowable = JSON.parse(decodeURIComponent(jsonStr));
364
+ } catch {
365
+ flow.flowable = "any";
366
+ }
367
+ }
368
+ }
369
+
370
+ // Find start action
371
+ const startActionLink = links.find(l =>
372
+ l.source === flowUri && l.predicate === "ad4m://startAction"
373
+ );
374
+ if (startActionLink) {
375
+ try {
376
+ const jsonStr = startActionLink.target.replace('literal://string:', '');
377
+ flow.startAction = JSON.parse(decodeURIComponent(jsonStr));
378
+ } catch {
379
+ // Ignore parse errors
380
+ }
381
+ }
382
+
383
+ // Find states
384
+ const stateLinks = links.filter(l =>
385
+ l.source === flowUri && l.predicate === "ad4m://hasState"
386
+ );
387
+
388
+ // Build a map from state URI to state name for later lookup
389
+ const stateUriToName = new Map<string, string>();
390
+
391
+ for (const stateLink of stateLinks) {
392
+ const stateUri = stateLink.target;
393
+
394
+ // Get state name
395
+ const nameLink = links.find(l =>
396
+ l.source === stateUri && l.predicate === "ad4m://stateName"
397
+ );
398
+ const stateName = nameLink ? Literal.fromUrl(nameLink.target).get() as string : "";
399
+
400
+ // Store mapping for transition lookup
401
+ stateUriToName.set(stateUri, stateName);
402
+
403
+ // Get state value
404
+ const valueLink = links.find(l =>
405
+ l.source === stateUri && l.predicate === "ad4m://stateValue"
406
+ );
407
+ const stateValue = valueLink ? Literal.fromUrl(valueLink.target).get() as number : 0;
408
+
409
+ // Get state check
410
+ const checkLink = links.find(l =>
411
+ l.source === stateUri && l.predicate === "ad4m://stateCheck"
412
+ );
413
+ let stateCheck: LinkPattern = { predicate: "", target: "" };
414
+ if (checkLink) {
415
+ try {
416
+ const jsonStr = checkLink.target.replace('literal://string:', '');
417
+ stateCheck = JSON.parse(decodeURIComponent(jsonStr));
418
+ } catch {
419
+ // Ignore parse errors
420
+ }
421
+ }
422
+
423
+ flow.addState({ name: stateName, value: stateValue, stateCheck });
424
+ }
425
+
426
+ // Find transitions
427
+ const transitionLinks = links.filter(l =>
428
+ l.source === flowUri && l.predicate === "ad4m://hasTransition"
429
+ );
430
+
431
+ for (const transitionLink of transitionLinks) {
432
+ const transitionUri = transitionLink.target;
433
+
434
+ // Get action name
435
+ const actionNameLink = links.find(l =>
436
+ l.source === transitionUri && l.predicate === "ad4m://actionName"
437
+ );
438
+ const actionName = actionNameLink ? Literal.fromUrl(actionNameLink.target).get() as string : "";
439
+
440
+ // Get from state
441
+ const fromStateLink = links.find(l =>
442
+ l.source === transitionUri && l.predicate === "ad4m://fromState"
443
+ );
444
+ const fromStateUri = fromStateLink?.target || "";
445
+ const fromState = stateUriToName.get(fromStateUri) || "";
446
+
447
+ // Get to state
448
+ const toStateLink = links.find(l =>
449
+ l.source === transitionUri && l.predicate === "ad4m://toState"
450
+ );
451
+ const toStateUri = toStateLink?.target || "";
452
+ const toState = stateUriToName.get(toStateUri) || "";
453
+
454
+ // Get actions
455
+ const actionsLink = links.find(l =>
456
+ l.source === transitionUri && l.predicate === "ad4m://transitionActions"
457
+ );
458
+ let actions: AD4MAction[] = [];
459
+ if (actionsLink) {
460
+ try {
461
+ const jsonStr = actionsLink.target.replace('literal://string:', '');
462
+ actions = JSON.parse(decodeURIComponent(jsonStr));
463
+ } catch {
464
+ // Ignore parse errors
465
+ }
466
+ }
467
+
468
+ flow.addTransition({ actionName, fromState, toState, actions });
469
+ }
470
+
471
+ return flow;
472
+ }
473
+
474
+ /**
475
+ * Convert to JSON representation
476
+ */
477
+ toJSON(): object {
478
+ return {
479
+ name: this.name,
480
+ namespace: this.namespace,
481
+ flowable: this.flowable,
482
+ startAction: this.startAction,
483
+ states: this._states,
484
+ transitions: this._transitions
485
+ };
486
+ }
487
+
488
+ /**
489
+ * Create from JSON representation
490
+ */
491
+ static fromJSON(json: any): SHACLFlow {
492
+ const flow = new SHACLFlow(json.name, json.namespace);
493
+ flow.flowable = json.flowable || "any";
494
+ flow.startAction = json.startAction || [];
495
+ for (const state of json.states || []) {
496
+ flow.addState(state);
497
+ }
498
+ for (const transition of json.transitions || []) {
499
+ flow.addTransition(transition);
500
+ }
501
+ return flow;
502
+ }
503
+ }