@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
@@ -31,3 +31,5 @@ export * from "./ai/AIClient";
31
31
  export * from "./ai/Tasks";
32
32
  export * from "./runtime/RuntimeResolver";
33
33
  export * from './model/Ad4mModel';
34
+ export * from './shacl/SHACLShape';
35
+ export { SHACLFlow, FlowState, FlowTransition, LinkPattern, FlowableCondition } from './shacl/SHACLFlow';
package/lib/src/index.js CHANGED
@@ -31,3 +31,5 @@ export * from "./ai/AIClient";
31
31
  export * from "./ai/Tasks";
32
32
  export * from "./runtime/RuntimeResolver";
33
33
  export * from './model/Ad4mModel';
34
+ export * from './shacl/SHACLShape';
35
+ export { SHACLFlow } from './shacl/SHACLFlow';
@@ -1424,8 +1424,12 @@ WHERE ${whereConditions.join(' AND ')}
1424
1424
  let convertedValue = target;
1425
1425
  // Only process if target has a value
1426
1426
  if (target !== undefined && target !== null && target !== '') {
1427
- // Check if we need to resolve a non-literal language expression
1428
- if (propMeta.resolveLanguage != undefined && propMeta.resolveLanguage !== 'literal' && typeof target === 'string') {
1427
+ // Check if we need to resolve a non-literal language expression.
1428
+ // resolveLanguage must be defined and not 'literal' to trigger expression resolution.
1429
+ // Also skip if the target itself is a literal:// URI — those are handled by the
1430
+ // literal-parsing branch below (avoids calling getExpression on empty literals like
1431
+ // "literal://string:" which would cause a deserialization error).
1432
+ if (propMeta.resolveLanguage != undefined && propMeta.resolveLanguage !== 'literal' && typeof target === 'string' && !target.startsWith('literal://')) {
1429
1433
  // For non-literal languages, resolve the expression via perspective.getExpression()
1430
1434
  // Note: Literals are already parsed by SurrealDB's fn::parse_literal()
1431
1435
  try {
@@ -1447,8 +1451,10 @@ WHERE ${whereConditions.join(' AND ')}
1447
1451
  convertedValue = target; // Fall back to raw value
1448
1452
  }
1449
1453
  }
1450
- else if (typeof target === 'string' && target.startsWith('literal://')) {
1451
- // Fallback: If we somehow got a literal URL that wasn't parsed by SurrealDB, parse it now
1454
+ else if (propMeta.resolveLanguage === 'literal' && typeof target === 'string' && target.startsWith('literal://')) {
1455
+ // Only parse literal URIs when resolveLanguage is explicitly set to 'literal'.
1456
+ // Without this check, properties pointing to baseExpressions of other models
1457
+ // (which may be literal:// strings) would get unwrapped, breaking link URI validation.
1452
1458
  try {
1453
1459
  const parsed = Literal.fromUrl(target).get();
1454
1460
  if (parsed.data !== undefined) {
@@ -1949,6 +1955,10 @@ WHERE ${whereConditions.join(' AND ')}
1949
1955
  const actions = this.generatePropertySetterAction(key, metadata);
1950
1956
  // Get resolve language from metadata (replaces Prolog query)
1951
1957
  let resolveLanguage = metadata.resolveLanguage;
1958
+ // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal://string:)
1959
+ if (value === undefined || value === null || value === "") {
1960
+ return;
1961
+ }
1952
1962
  if (resolveLanguage) {
1953
1963
  value = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").createExpression(value, resolveLanguage);
1954
1964
  }
@@ -2043,8 +2053,10 @@ WHERE ${whereConditions.join(' AND ')}
2043
2053
  initialValues[key] = value;
2044
2054
  }
2045
2055
  }
2056
+ // Get the class name instead of passing the instance to avoid Prolog query generation
2057
+ const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
2046
2058
  // Create the subject with the initial values
2047
- await this.perspective.createSubject(this, __classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f"), initialValues, batchId);
2059
+ await this.perspective.createSubject(className, __classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f"), initialValues, batchId);
2048
2060
  // Link the subject to the source
2049
2061
  await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").add(new Link({ source: __classPrivateFieldGet(this, _Ad4mModel_source, "f"), predicate: "ad4m://has_child", target: this.baseExpression }), 'shared', batchId);
2050
2062
  // Set collections
@@ -1,5 +1,6 @@
1
1
  import { Subject } from "./Subject";
2
- import { capitalize, propertyNameToSetterName, singularToPlural, stringifyObjectLiteral } from "./util";
2
+ import { capitalize, propertyNameToSetterName, stringifyObjectLiteral } from "./util";
3
+ import { SHACLShape } from "../shacl/SHACLShape";
3
4
  export class PerspectiveAction {
4
5
  }
5
6
  export function addLink(source, predicate, target) {
@@ -90,8 +91,8 @@ export function InstanceQuery(options) {
90
91
  // Prolog failed, fall through to SurrealDB
91
92
  }
92
93
  // Fallback to SurrealDB (SdnaOnly mode)
93
- // Get all instances first
94
- let allInstances = await perspective.getAllSubjectInstances(subjectClassName);
94
+ // Get all instances first - pass the class constructor, not just the name
95
+ let allInstances = await perspective.getAllSubjectInstances(target);
95
96
  // Filter by where clause if provided
96
97
  if (options && options.where) {
97
98
  let filtered = [];
@@ -572,9 +573,9 @@ export function ModelOptions(opts) {
572
573
  target: "value",
573
574
  ...(local && { local: true })
574
575
  }];
575
- collectionCode += `collection_adder(${uuid}, "${singularToPlural(collection)}", '${stringifyObjectLiteral(collectionAdderAction)}').\n`;
576
- collectionCode += `collection_remover(${uuid}, "${singularToPlural(collection)}", '${stringifyObjectLiteral(collectionRemoverAction)}').\n`;
577
- collectionCode += `collection_setter(${uuid}, "${singularToPlural(collection)}", '${stringifyObjectLiteral(collectionSetterAction)}').\n`;
576
+ collectionCode += `collection_adder(${uuid}, "${collection}", '${stringifyObjectLiteral(collectionAdderAction)}').\n`;
577
+ collectionCode += `collection_remover(${uuid}, "${collection}", '${stringifyObjectLiteral(collectionRemoverAction)}').\n`;
578
+ collectionCode += `collection_setter(${uuid}, "${collection}", '${stringifyObjectLiteral(collectionSetterAction)}').\n`;
578
579
  }
579
580
  collectionsCode.push(collectionCode);
580
581
  }
@@ -595,6 +596,195 @@ export function ModelOptions(opts) {
595
596
  name: subjectName
596
597
  };
597
598
  };
599
+ // Generate SHACL shape (W3C standard + AD4M action definitions)
600
+ target.generateSHACL = function () {
601
+ const subjectName = opts.name;
602
+ const obj = target.prototype;
603
+ // Determine namespace from first property or collection, or use default
604
+ let namespace = "ad4m://";
605
+ const properties = obj.__properties || {};
606
+ const collections = obj.__collections || {};
607
+ // Try properties first
608
+ if (Object.keys(properties).length > 0) {
609
+ const firstProp = properties[Object.keys(properties)[0]];
610
+ if (firstProp.through) {
611
+ // Extract namespace from through predicate (e.g., "recipe://name" -> "recipe://")
612
+ const match = firstProp.through.match(/^([^:]+:\/\/)/);
613
+ if (match) {
614
+ namespace = match[1];
615
+ }
616
+ }
617
+ }
618
+ // Fall back to collections if no properties
619
+ else if (Object.keys(collections).length > 0) {
620
+ const firstColl = collections[Object.keys(collections)[0]];
621
+ if (firstColl.through) {
622
+ const match = firstColl.through.match(/^([^:]+:\/\/)/);
623
+ if (match) {
624
+ namespace = match[1];
625
+ }
626
+ }
627
+ }
628
+ // Create SHACL shape
629
+ const shapeUri = `${namespace}${subjectName}Shape`;
630
+ const targetClass = `${namespace}${subjectName}`;
631
+ const shape = new SHACLShape(shapeUri, targetClass);
632
+ // === Extract Constructor Actions (same logic as generateSDNA) ===
633
+ let constructorActions = [];
634
+ if (obj.subjectConstructor && obj.subjectConstructor.length) {
635
+ constructorActions = constructorActions.concat(obj.subjectConstructor);
636
+ }
637
+ // === Extract Destructor Actions ===
638
+ let destructorActions = [];
639
+ // Convert properties to SHACL property shapes
640
+ for (const propName in properties) {
641
+ const propMeta = properties[propName];
642
+ if (!propMeta.through)
643
+ continue; // Skip properties without predicates
644
+ const propShape = {
645
+ name: propName,
646
+ path: propMeta.through,
647
+ };
648
+ // Determine datatype from initial value or resolveLanguage
649
+ if (propMeta.resolveLanguage === "literal") {
650
+ // If it resolves via literal language, it's likely a string
651
+ propShape.datatype = "xsd://string";
652
+ }
653
+ else if (propMeta.initial) {
654
+ // Try to infer from initial value type
655
+ const initialType = typeof obj[propName];
656
+ if (initialType === "number") {
657
+ propShape.datatype = "xsd://integer";
658
+ }
659
+ else if (initialType === "boolean") {
660
+ propShape.datatype = "xsd://boolean";
661
+ }
662
+ else if (initialType === "string") {
663
+ propShape.datatype = "xsd://string";
664
+ }
665
+ }
666
+ // Cardinality constraints
667
+ if (propMeta.required) {
668
+ propShape.minCount = 1;
669
+ }
670
+ // Single-valued properties get maxCount 1
671
+ // (collections are handled separately below)
672
+ if (!propMeta.collection) {
673
+ propShape.maxCount = 1;
674
+ }
675
+ // Flag properties have fixed value
676
+ if (propMeta.flag && propMeta.initial) {
677
+ propShape.hasValue = propMeta.initial;
678
+ }
679
+ // AD4M-specific metadata
680
+ if (propMeta.local !== undefined) {
681
+ propShape.local = propMeta.local;
682
+ }
683
+ if (propMeta.writable !== undefined) {
684
+ propShape.writable = propMeta.writable;
685
+ }
686
+ if (propMeta.resolveLanguage) {
687
+ propShape.resolveLanguage = propMeta.resolveLanguage;
688
+ }
689
+ // === Extract Setter Actions (same logic as generateSDNA) ===
690
+ if (propMeta.setter) {
691
+ // Custom setter defined - not yet supported in SHACL
692
+ console.warn(`[SHACL Generation] Custom Prolog setter for property '${propName}' in class '${subjectName}' is not yet supported. ` +
693
+ `The property will be created without setter actions. Consider using standard writable properties or provide explicit SHACL JSON.`);
694
+ // TODO: Parse custom Prolog setter to extract actions
695
+ }
696
+ else if (propMeta.writable && propMeta.through) {
697
+ let setter = obj[propertyNameToSetterName(propName)];
698
+ if (typeof setter === "function") {
699
+ propShape.setter = [{
700
+ action: "setSingleTarget",
701
+ source: "this",
702
+ predicate: propMeta.through,
703
+ target: "value",
704
+ ...(propMeta.local && { local: true })
705
+ }];
706
+ }
707
+ }
708
+ // Add to constructor actions if property has initial value
709
+ if (propMeta.initial) {
710
+ constructorActions.push({
711
+ action: "addLink",
712
+ source: "this",
713
+ predicate: propMeta.through,
714
+ target: propMeta.initial,
715
+ });
716
+ // Add to destructor actions
717
+ destructorActions.push({
718
+ action: "removeLink",
719
+ source: "this",
720
+ predicate: propMeta.through,
721
+ target: "*",
722
+ });
723
+ }
724
+ shape.addProperty(propShape);
725
+ }
726
+ // Convert collections to SHACL property shapes
727
+ // (collections variable already declared above for namespace inference)
728
+ for (const collName in collections) {
729
+ const collMeta = collections[collName];
730
+ if (!collMeta.through)
731
+ continue;
732
+ const collShape = {
733
+ name: collName,
734
+ path: collMeta.through,
735
+ // Collections have no maxCount (unlimited)
736
+ // minCount defaults to 0 (optional)
737
+ };
738
+ // Determine if it's a reference (IRI) or literal
739
+ // Collections typically contain references (IRIs) to other entities
740
+ // They're literals only if explicitly marked or contain primitive values
741
+ if (collMeta.where?.isInstance) {
742
+ // Collection of typed entities - definitely IRIs
743
+ collShape.nodeKind = 'IRI';
744
+ }
745
+ else {
746
+ // Default to IRI for collections (most common case)
747
+ // Literal collections are rare and would need explicit marking
748
+ collShape.nodeKind = 'IRI';
749
+ }
750
+ // AD4M-specific metadata
751
+ if (collMeta.local !== undefined) {
752
+ collShape.local = collMeta.local;
753
+ }
754
+ if (collMeta.writable !== undefined) {
755
+ collShape.writable = collMeta.writable;
756
+ }
757
+ // === Extract Collection Actions (adder/remover) ===
758
+ // Adder action - adds a link to the collection
759
+ collShape.adder = [{
760
+ action: "addLink",
761
+ source: "this",
762
+ predicate: collMeta.through,
763
+ target: "value",
764
+ ...(collMeta.local && { local: true })
765
+ }];
766
+ // Remover action - removes a link from the collection
767
+ collShape.remover = [{
768
+ action: "removeLink",
769
+ source: "this",
770
+ predicate: collMeta.through,
771
+ target: "value",
772
+ ...(collMeta.local && { local: true })
773
+ }];
774
+ shape.addProperty(collShape);
775
+ }
776
+ // Set constructor and destructor actions on the shape
777
+ if (constructorActions.length > 0) {
778
+ shape.setConstructorActions(constructorActions);
779
+ }
780
+ if (destructorActions.length > 0) {
781
+ shape.setDestructorActions(destructorActions);
782
+ }
783
+ return {
784
+ shape,
785
+ name: subjectName
786
+ };
787
+ };
598
788
  Object.defineProperty(target, 'type', { configurable: true });
599
789
  };
600
790
  }
@@ -7,6 +7,6 @@ export declare function collectionToAdderName(collection: string): string;
7
7
  export declare function collectionAdderToName(adderName: string): string;
8
8
  export declare function collectionToRemoverName(collection: string): string;
9
9
  export declare function collectionRemoverToName(removerName: string): string;
10
- export declare function collectionSetterToName(adderName: string): string;
10
+ export declare function collectionSetterToName(setterName: string): string;
11
11
  export declare function collectionToSetterName(collection: string): string;
12
12
  export declare function stringifyObjectLiteral(obj: any): any;
@@ -32,26 +32,29 @@ export function pluralToSingular(plural) {
32
32
  export function collectionToAdderName(collection) {
33
33
  return `add${capitalize(pluralToSingular(collection))}`;
34
34
  }
35
- // e.g. "addEntry" -> "entries"
35
+ // e.g. "addComments" -> "comments"
36
36
  export function collectionAdderToName(adderName) {
37
- let singular = adderName.substring(3);
38
- let plural = singularToPlural(singular);
39
- return plural.charAt(0).toLowerCase() + plural.slice(1);
37
+ // Extract the collection name after "add" and lowercase first char
38
+ // The method name already has the plural collection name (e.g., "addComments")
39
+ let collectionName = adderName.substring(3);
40
+ return collectionName.charAt(0).toLowerCase() + collectionName.slice(1);
40
41
  }
41
42
  // e.g. "comments" -> "removeComment"
42
43
  export function collectionToRemoverName(collection) {
43
44
  return `remove${capitalize(pluralToSingular(collection))}`;
44
45
  }
45
- // e.g. "removeEntry" -> "entries"
46
+ // e.g. "removeComments" -> "comments"
46
47
  export function collectionRemoverToName(removerName) {
47
- let singular = removerName.substring(6);
48
- let plural = singularToPlural(singular);
49
- return plural.charAt(0).toLowerCase() + plural.slice(1);
48
+ // Extract the collection name after "remove" and lowercase first char
49
+ // The method name already has the plural collection name (e.g., "removeComments")
50
+ let collectionName = removerName.substring(6);
51
+ return collectionName.charAt(0).toLowerCase() + collectionName.slice(1);
50
52
  }
51
- export function collectionSetterToName(adderName) {
52
- let singular = adderName.substring(13);
53
- let plural = singularToPlural(singular);
54
- return plural.charAt(0).toLowerCase() + plural.slice(1);
53
+ export function collectionSetterToName(setterName) {
54
+ // Extract the collection name after "setCollection" and lowercase first char
55
+ // The method name already has the plural collection name (e.g., "setCollectionComments")
56
+ let collectionName = setterName.substring(13);
57
+ return collectionName.charAt(0).toLowerCase() + collectionName.slice(1);
55
58
  }
56
59
  // e.g. "comments" -> "addComment"
57
60
  export function collectionToSetterName(collection) {
@@ -64,7 +64,17 @@ export declare class PerspectiveClient {
64
64
  addLinkExpression(uuid: string, link: LinkExpression, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
65
65
  updateLink(uuid: string, oldLink: LinkExpressionInput, newLink: Link, batchId?: string): Promise<LinkExpression>;
66
66
  removeLink(uuid: string, link: LinkExpressionInput, batchId?: string): Promise<boolean>;
67
- addSdna(uuid: string, name: string, sdnaCode: string, sdnaType: "subject_class" | "flow" | "custom"): Promise<boolean>;
67
+ /**
68
+ * Adds Social DNA code to a perspective.
69
+ *
70
+ * Preferred usage: pass shaclJson (from SHACLShape.toJSON()) as the primary schema definition.
71
+ * The sdnaCode parameter is kept for backward compatibility but SHACL is the source of truth
72
+ * for all SDNA operations. Prolog engines remain available for complex queries.
73
+ *
74
+ * @param sdnaCode - Legacy Prolog code (pass empty string when using shaclJson)
75
+ * @param shaclJson - SHACL JSON string from SHACLShape.toJSON() (recommended)
76
+ */
77
+ addSdna(uuid: string, name: string, sdnaCode: string | undefined, sdnaType: "subject_class" | "flow" | "custom", shaclJson?: string): Promise<boolean>;
68
78
  executeCommands(uuid: string, commands: string, expression: string, parameters: string, batchId?: string): Promise<boolean>;
69
79
  createSubject(uuid: string, subjectClass: string, expressionAddress: string, initialValues?: string, batchId?: string): Promise<boolean>;
70
80
  getSubjectData(uuid: string, subjectClass: string, expressionAddress: string): Promise<string>;
@@ -392,11 +392,22 @@ export class PerspectiveClient {
392
392
  }));
393
393
  return perspectiveRemoveLink;
394
394
  }
395
- async addSdna(uuid, name, sdnaCode, sdnaType) {
395
+ /**
396
+ * Adds Social DNA code to a perspective.
397
+ *
398
+ * Preferred usage: pass shaclJson (from SHACLShape.toJSON()) as the primary schema definition.
399
+ * The sdnaCode parameter is kept for backward compatibility but SHACL is the source of truth
400
+ * for all SDNA operations. Prolog engines remain available for complex queries.
401
+ *
402
+ * @param sdnaCode - Legacy Prolog code (pass empty string when using shaclJson)
403
+ * @param shaclJson - SHACL JSON string from SHACLShape.toJSON() (recommended)
404
+ */
405
+ async addSdna(uuid, name, sdnaCode, sdnaType, shaclJson) {
396
406
  return unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
397
- mutation: gql `mutation perspectiveAddSdna($uuid: String!, $name: String!, $sdnaCode: String!, $sdnaType: String!) {
398
- perspectiveAddSdna(uuid: $uuid, name: $name, sdnaCode: $sdnaCode, sdnaType: $sdnaType)
399
- }`, variables: { uuid, name, sdnaCode, sdnaType }
407
+ mutation: gql `mutation perspectiveAddSdna($uuid: String!, $name: String!, $sdnaCode: String, $sdnaType: String!, $shaclJson: String) {
408
+ perspectiveAddSdna(uuid: $uuid, name: $name, sdnaCode: $sdnaCode, sdnaType: $sdnaType, shaclJson: $shaclJson)
409
+ }`,
410
+ variables: { uuid, name, sdnaCode: sdnaCode || "", sdnaType, shaclJson }
400
411
  })).perspectiveAddSdna;
401
412
  }
402
413
  async executeCommands(uuid, commands, expression, parameters, batchId) {
@@ -8,6 +8,8 @@ import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
8
8
  import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
9
9
  import { AIClient } from "../ai/AIClient";
10
10
  import { AllInstancesResult } from "../model/Ad4mModel";
11
+ import { SHACLShape } from "../shacl/SHACLShape";
12
+ import { SHACLFlow } from "../shacl/SHACLFlow";
11
13
  type QueryCallback = (result: AllInstancesResult) => void;
12
14
  /** Proxy object for a subscribed Prolog query that provides real-time updates
13
15
  *
@@ -529,9 +531,115 @@ export declare class PerspectiveProxy {
529
531
  * This will return the SDNA code for the specified class, or null if not found.
530
532
  */
531
533
  getSdnaForClass(className: string): Promise<string | null>;
532
- /** Adds the given Social DNA code to the perspective's SDNA code */
533
- addSdna(name: string, sdnaCode: string, sdnaType: "subject_class" | "flow" | "custom"): Promise<boolean>;
534
- /** Returns all the Subject classes defined in this perspectives SDNA */
534
+ /**
535
+ * Adds Social DNA code to the perspective.
536
+ *
537
+ * **Recommended:** Use {@link addShacl} instead, which accepts the `SHACLShape` type directly.
538
+ * This method is primarily for the GraphQL layer and legacy Prolog code.
539
+ *
540
+ * @param name - Unique name for this SDNA definition
541
+ * @param sdnaCode - Prolog SDNA code (legacy, can be empty string if shaclJson provided)
542
+ * @param sdnaType - Type of SDNA: "subject_class", "flow", or "custom"
543
+ * @param shaclJson - SHACL JSON string (use addShacl() for type-safe alternative)
544
+ *
545
+ * @example
546
+ * // Recommended: Use addShacl() with SHACLShape type
547
+ * const shape = new SHACLShape('recipe://Recipe');
548
+ * shape.addProperty({ name: 'title', path: 'recipe://title', datatype: 'xsd:string' });
549
+ * await perspective.addShacl('Recipe', shape);
550
+ *
551
+ * // Legacy: Prolog code is auto-converted to SHACL
552
+ * await perspective.addSdna('Recipe', prologCode, 'subject_class');
553
+ */
554
+ addSdna(name: string, sdnaCode: string, sdnaType: "subject_class" | "flow" | "custom", shaclJson?: string): Promise<boolean>;
555
+ /**
556
+ * **Recommended way to add SDNA schemas.**
557
+ *
558
+ * Store a SHACL shape in this Perspective using the type-safe `SHACLShape` class.
559
+ * The shape is serialized as RDF triples (links) for native AD4M storage and querying.
560
+ *
561
+ * @param name - Unique name for this schema (e.g., 'Recipe', 'Task')
562
+ * @param shape - SHACLShape instance defining the schema
563
+ *
564
+ * @example
565
+ * import { SHACLShape } from '@coasys/ad4m';
566
+ *
567
+ * const shape = new SHACLShape('recipe://Recipe');
568
+ * shape.addProperty({
569
+ * name: 'title',
570
+ * path: 'recipe://title',
571
+ * datatype: 'xsd:string',
572
+ * minCount: 1
573
+ * });
574
+ * shape.addProperty({
575
+ * name: 'ingredients',
576
+ * path: 'recipe://has_ingredient',
577
+ * // No maxCount = collection
578
+ * });
579
+ *
580
+ * await perspective.addShacl('Recipe', shape);
581
+ */
582
+ addShacl(name: string, shape: SHACLShape): Promise<void>;
583
+ /**
584
+ * Retrieve a SHACL shape by name from this Perspective
585
+ */
586
+ getShacl(name: string): Promise<SHACLShape | null>;
587
+ /**
588
+ * Get all SHACL shapes stored in this Perspective
589
+ */
590
+ getAllShacl(): Promise<Array<{
591
+ name: string;
592
+ shape: SHACLShape;
593
+ }>>;
594
+ /**
595
+ * **Recommended way to add Flow definitions.**
596
+ *
597
+ * Store a SHACL Flow (state machine) in this Perspective using the type-safe `SHACLFlow` class.
598
+ * The flow is serialized as RDF triples (links) for native AD4M storage and querying.
599
+ *
600
+ * @param name - Flow name (e.g., 'TODO', 'Approval')
601
+ * @param flow - SHACLFlow instance defining the state machine
602
+ *
603
+ * @example
604
+ * ```typescript
605
+ * import { SHACLFlow } from '@coasys/ad4m';
606
+ *
607
+ * const todoFlow = new SHACLFlow('TODO', 'todo://');
608
+ * todoFlow.flowable = 'any';
609
+ *
610
+ * // Define states
611
+ * todoFlow.addState({ name: 'ready', value: 0, stateCheck: { predicate: 'todo://state', target: 'todo://ready' }});
612
+ * todoFlow.addState({ name: 'done', value: 1, stateCheck: { predicate: 'todo://state', target: 'todo://done' }});
613
+ *
614
+ * // Define start action
615
+ * todoFlow.startAction = [{ action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }];
616
+ *
617
+ * // Define transitions
618
+ * todoFlow.addTransition({
619
+ * actionName: 'Complete',
620
+ * fromState: 'ready',
621
+ * toState: 'done',
622
+ * actions: [
623
+ * { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://done' },
624
+ * { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
625
+ * ]
626
+ * });
627
+ *
628
+ * await perspective.addFlow('TODO', todoFlow);
629
+ * ```
630
+ */
631
+ addFlow(name: string, flow: SHACLFlow): Promise<void>;
632
+ /**
633
+ * Retrieve a Flow definition by name from this Perspective
634
+ *
635
+ * @param name - Flow name to retrieve
636
+ * @returns The SHACLFlow or null if not found
637
+ */
638
+ getFlow(name: string): Promise<SHACLFlow | null>;
639
+ /** Returns all the Subject classes defined in this perspectives SDNA
640
+ *
641
+ * Uses SHACL-based lookup (Prolog-free implementation).
642
+ */
535
643
  subjectClasses(): Promise<string[]>;
536
644
  stringOrTemplateObjectToSubjectClassName<T>(subjectClass: T): Promise<string>;
537
645
  /**
@@ -548,6 +656,11 @@ export declare class PerspectiveProxy {
548
656
  */
549
657
  createSubject<T, B extends string | undefined = undefined>(subjectClass: T, exprAddr: string, initialValues?: Record<string, any>, batchId?: B): Promise<B extends undefined ? T : string>;
550
658
  getSubjectData<T>(subjectClass: T, exprAddr: string): Promise<T>;
659
+ /**
660
+ * Gets actions from SHACL links for a given predicate (e.g., ad4m://constructor, ad4m://destructor).
661
+ * Returns the parsed action array if found, or null if not found.
662
+ */
663
+ private getActionsFromSHACL;
551
664
  /** Removes a subject instance by running its (SDNA defined) destructor,
552
665
  * which means removing links around the given expression address
553
666
  *
@@ -577,10 +690,8 @@ export declare class PerspectiveProxy {
577
690
  */
578
691
  getSubjectProxy<T>(base: string, subjectClass: T): Promise<T>;
579
692
  /**
580
- * Extracts subject class metadata from SDNA by parsing the Prolog text.
581
- * Parses the instance rule to extract required predicates.
582
- * Returns required predicates that define what makes something an instance,
583
- * plus a map of property/collection names to their predicates.
693
+ * Gets subject class metadata from SHACL links using SHACLShape.fromLinks().
694
+ * Retrieves the SHACL shape and extracts metadata for instance queries.
584
695
  */
585
696
  getSubjectClassMetadataFromSDNA(className: string): Promise<{
586
697
  requiredPredicates: string[];
@@ -649,7 +760,12 @@ export declare class PerspectiveProxy {
649
760
  * that match the given properties will be used.
650
761
  */
651
762
  getAllSubjectProxies<T>(subjectClass: T): Promise<T[]>;
652
- private buildQueryFromTemplate;
763
+ /**
764
+ * Find a subject class by matching an object's properties/collections against SHACL shapes.
765
+ * Queries SHACL links client-side to find a class whose properties contain all required ones.
766
+ * @returns The matching class name, or null if no match found.
767
+ */
768
+ private findClassByProperties;
653
769
  /** Returns all subject classes that match the given template object.
654
770
  * This function looks at the properties of the template object and
655
771
  * its setters and collections to create a Prolog query that finds