@coasys/ad4m 0.11.2-dev-sdna-only-prolog-2 → 0.11.2-dev.3

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.
@@ -93,6 +93,8 @@ export interface PropertyMetadata {
93
93
  getter?: string;
94
94
  /** Custom Prolog setter code */
95
95
  setter?: string;
96
+ /** Custom SurrealQL getter code */
97
+ surrealGetter?: string;
96
98
  /** Whether stored locally only */
97
99
  local?: boolean;
98
100
  /** Transform function */
@@ -111,6 +113,8 @@ export interface CollectionMetadata {
111
113
  predicate: string;
112
114
  /** Filter conditions */
113
115
  where?: { isInstance?: any; condition?: string };
116
+ /** Custom SurrealQL getter code */
117
+ surrealGetter?: string;
114
118
  /** Whether stored locally only */
115
119
  local?: boolean;
116
120
  }
@@ -503,6 +507,7 @@ export class Ad4mModel {
503
507
  ...(options.initial !== undefined && { initial: options.initial }),
504
508
  ...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
505
509
  ...(options.getter !== undefined && { getter: options.getter }),
510
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter }),
506
511
  ...(options.setter !== undefined && { setter: options.setter }),
507
512
  ...(options.local !== undefined && { local: options.local }),
508
513
  ...(options.transform !== undefined && { transform: options.transform }),
@@ -520,7 +525,8 @@ export class Ad4mModel {
520
525
  name: collectionName,
521
526
  predicate: options.through || "",
522
527
  ...(options.where !== undefined && { where: options.where }),
523
- ...(options.local !== undefined && { local: options.local })
528
+ ...(options.local !== undefined && { local: options.local }),
529
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter })
524
530
  };
525
531
  }
526
532
 
@@ -639,6 +645,11 @@ export class Ad4mModel {
639
645
  * @private
640
646
  */
641
647
  private generatePropertySetterAction(key: string, metadata: PropertyOptions): any[] {
648
+ // Check if property is read-only
649
+ if (metadata.writable === false) {
650
+ throw new Error(`Property "${key}" is read-only and cannot be written`);
651
+ }
652
+
642
653
  if (metadata.setter) {
643
654
  // Custom setter - throw error for now (Phase 2)
644
655
  throw new Error(
@@ -744,27 +755,7 @@ export class Ad4mModel {
744
755
 
745
756
  private async getData() {
746
757
  // Builds an object with the author, timestamp, all properties, & all collections on the Ad4mModel and saves it to the instance
747
- const subQueries = [buildAuthorAndTimestampQuery(), buildPropertiesQuery(), buildCollectionsQuery()];
748
- const fullQuery = `
749
- Base = "${this.#baseExpression}",
750
- subject_class("${this.#subjectClassName}", SubjectClass),
751
- ${subQueries.join(", ")}
752
- `;
753
-
754
- // Try Prolog first
755
- try {
756
- const result = await this.#perspective.infer(fullQuery);
757
- if (result?.[0] && result[0].Properties && result[0].Properties.length > 0) {
758
- const { Properties, Collections, Timestamp, Author } = result[0];
759
- const values = [...Properties, ...Collections, ["timestamp", Timestamp], ["author", Author]];
760
- await Ad4mModel.assignValuesToInstance(this.#perspective, this, values);
761
- return this;
762
- }
763
- } catch (e) {
764
- console.log(`Prolog getData failed for ${this.#baseExpression}, falling back to SurrealDB`);
765
- }
766
-
767
- // Fallback to SurrealDB (SdnaOnly mode)
758
+ // Use SurrealDB for data queries
768
759
  try {
769
760
  const ctor = this.constructor as typeof Ad4mModel;
770
761
  const metadata = ctor.getModelMetadata();
@@ -772,6 +763,9 @@ export class Ad4mModel {
772
763
  // Query for all links from this specific node (base expression)
773
764
  // Using formatSurrealValue to prevent SQL injection by properly escaping the value
774
765
  const safeBaseExpression = ctor.formatSurrealValue(this.#baseExpression);
766
+ // Note: We use ORDER BY timestamp ASC because:
767
+ // - For collections: we want chronological order (oldest to newest)
768
+ // - For properties: we select the LAST element to get "latest wins" semantics
775
769
  const linksQuery = `
776
770
  SELECT id, predicate, out.uri AS target, author, timestamp
777
771
  FROM link
@@ -784,11 +778,14 @@ export class Ad4mModel {
784
778
  let maxTimestamp = null;
785
779
  let latestAuthor = null;
786
780
 
787
- // Process properties
781
+ // Process properties (skip those with surrealGetter)
788
782
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
783
+ if (propMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
789
784
  const matching = links.filter((l: any) => l.predicate === propMeta.predicate);
790
785
  if (matching.length > 0) {
791
- const link = matching[0]; // Take first/latest
786
+ // "Latest wins" semantics: select the last element since links are ordered ASC.
787
+ // The last element has the most recent timestamp and represents the current property value.
788
+ const link = matching[matching.length - 1];
792
789
  let value = link.target;
793
790
 
794
791
  // Track timestamp/author
@@ -830,11 +827,31 @@ export class Ad4mModel {
830
827
  }
831
828
  }
832
829
 
833
- // Process collections
830
+ // Process collections (skip those with surrealGetter)
834
831
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
832
+ if (collMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
835
833
  const matching = links.filter((l: any) => l.predicate === collMeta.predicate);
836
- // Links are already sorted by timestamp ASC from the query, so map preserves order
837
- (this as any)[collName] = matching.map((l: any) => l.target);
834
+ // Collections preserve chronological order: links are sorted ASC by timestamp,
835
+ // so the collection reflects the order in which items were added (oldest to newest).
836
+ let values = matching.map((l: any) => l.target);
837
+
838
+ // Apply where.isInstance filtering if present
839
+ if (collMeta.where?.isInstance && values.length > 0) {
840
+ try {
841
+ const className = typeof collMeta.where.isInstance === 'string'
842
+ ? collMeta.where.isInstance
843
+ : collMeta.where.isInstance.name;
844
+
845
+ const filterMetadata = await this.#perspective.getSubjectClassMetadataFromSDNA(className);
846
+ if (filterMetadata) {
847
+ values = await this.#perspective.batchCheckSubjectInstances(values, filterMetadata);
848
+ }
849
+ } catch (error) {
850
+ // Keep unfiltered values on error
851
+ }
852
+ }
853
+
854
+ (this as any)[collName] = values;
838
855
  }
839
856
 
840
857
  // Set author and timestamp
@@ -845,6 +862,9 @@ export class Ad4mModel {
845
862
  (this as any).timestamp = maxTimestamp;
846
863
  }
847
864
  }
865
+
866
+ // Evaluate SurrealQL getters
867
+ await ctor.evaluateSurrealGettersForInstance(this, this.#perspective, metadata);
848
868
  } catch (e) {
849
869
  console.error(`SurrealDB getData also failed for ${this.#baseExpression}:`, e);
850
870
  }
@@ -879,6 +899,60 @@ export class Ad4mModel {
879
899
  return fullQuery;
880
900
  }
881
901
 
902
+ /**
903
+ * Evaluates custom SurrealQL getters for properties and collections on a specific instance.
904
+ * @private
905
+ */
906
+ private static async evaluateSurrealGettersForInstance(
907
+ instance: any,
908
+ perspective: PerspectiveProxy,
909
+ metadata: any
910
+ ) {
911
+ const safeBaseExpression = this.formatSurrealValue(instance.baseExpression);
912
+
913
+ // Evaluate property surrealGetters
914
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
915
+ if ((propMeta as any).surrealGetter) {
916
+ try {
917
+ // Replace 'Base' placeholder with actual base expression
918
+ const query = (propMeta as any).surrealGetter.replace(/Base/g, safeBaseExpression);
919
+ // Query from node table to have graph traversal context
920
+ const result = await perspective.querySurrealDB(
921
+ `SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`
922
+ );
923
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null && result[0].value !== 'None' && result[0].value !== '') {
924
+ instance[propName] = result[0].value;
925
+ }
926
+ } catch (error) {
927
+ console.warn(`Failed to evaluate surrealGetter for ${propName}:`, error);
928
+ }
929
+ }
930
+ }
931
+
932
+ // Evaluate collection surrealGetters
933
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
934
+ if ((collMeta as any).surrealGetter) {
935
+ try {
936
+ // Replace 'Base' placeholder with actual base expression
937
+ const query = (collMeta as any).surrealGetter.replace(/Base/g, safeBaseExpression);
938
+ // Query from node table to have graph traversal context
939
+ const result = await perspective.querySurrealDB(
940
+ `SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`
941
+ );
942
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
943
+ // Filter out 'None' from collection results
944
+ const value = result[0].value;
945
+ instance[collName] = Array.isArray(value)
946
+ ? value.filter((v: any) => v && v !== '' && v !== 'None')
947
+ : value;
948
+ }
949
+ } catch (error) {
950
+ console.warn(`Failed to evaluate surrealGetter for ${collName}:`, error);
951
+ }
952
+ }
953
+ }
954
+ }
955
+
882
956
  /**
883
957
  * Generates a SurrealQL query from a Query object.
884
958
  *
@@ -1479,9 +1553,10 @@ WHERE ${whereConditions.join(' AND ')}
1479
1553
  latestAuthor = link.author;
1480
1554
  }
1481
1555
 
1482
- // Find matching property
1556
+ // Find matching property (skip those with surrealGetter)
1483
1557
  let foundProperty = false;
1484
1558
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1559
+ if (propMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
1485
1560
  if (propMeta.predicate === predicate) {
1486
1561
  // For properties, take the first value (or we could use timestamp to get latest)
1487
1562
  // Note: Empty objects {} are truthy, so we need to check for them explicitly
@@ -1548,9 +1623,10 @@ WHERE ${whereConditions.join(' AND ')}
1548
1623
  }
1549
1624
  }
1550
1625
 
1551
- // If not a property, check if it's a collection
1626
+ // If not a property, check if it's a collection (skip those with surrealGetter)
1552
1627
  if (!foundProperty) {
1553
1628
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1629
+ if (collMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
1554
1630
  if (collMeta.predicate === predicate) {
1555
1631
  // For collections, accumulate all values with their timestamps and indices for sorting
1556
1632
  if (!instance[collName]) {
@@ -1612,8 +1688,10 @@ WHERE ${whereConditions.join(' AND ')}
1612
1688
  // Use original index as tiebreaker for stable sorting
1613
1689
  return a.originalIndex - b.originalIndex;
1614
1690
  });
1615
- // Replace collection with sorted values
1616
- instance[collName] = pairs.map(p => p.value);
1691
+ // Replace collection with sorted values, filtering out empty strings and None
1692
+ instance[collName] = pairs
1693
+ .map(p => p.value)
1694
+ .filter((v: any) => v && v !== '' && v !== 'None');
1617
1695
  // Clean up temporary arrays
1618
1696
  delete instance[timestampsKey];
1619
1697
  delete instance[indicesKey];
@@ -1637,6 +1715,46 @@ WHERE ${whereConditions.join(' AND ')}
1637
1715
  }
1638
1716
  }
1639
1717
 
1718
+ // Evaluate SurrealQL getters for all instances
1719
+ for (const instance of instances) {
1720
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
1721
+ }
1722
+
1723
+ // Filter collections by where.isInstance if specified
1724
+ // Do this for all instances that have collections with filters
1725
+ for (const instance of instances) {
1726
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1727
+ if (collMeta.where?.isInstance && instance[collName]?.length > 0) {
1728
+ try {
1729
+ const targetClass = collMeta.where.isInstance;
1730
+ const subjects = instance[collName];
1731
+
1732
+ // Get the class metadata from SDNA to pass to batchCheckSubjectInstances
1733
+ const targetClassName = typeof targetClass === 'string'
1734
+ ? targetClass
1735
+ : (targetClass as any).prototype?.className || targetClass.name;
1736
+ const classMetadata = await perspective.getSubjectClassMetadataFromSDNA(targetClassName);
1737
+
1738
+ if (!classMetadata) {
1739
+ continue;
1740
+ }
1741
+
1742
+ // Check which subjects are instances of the target class
1743
+ const validSubjects = await perspective.batchCheckSubjectInstances(subjects, classMetadata);
1744
+
1745
+ instance[collName] = validSubjects;
1746
+ } catch (error) {
1747
+ // On error, leave the collection unfiltered rather than breaking everything
1748
+ }
1749
+ }
1750
+ }
1751
+ }
1752
+
1753
+ // Evaluate SurrealQL getters for all instances
1754
+ for (const instance of instances) {
1755
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
1756
+ }
1757
+
1640
1758
  // Filter by where conditions that couldn't be filtered in SQL
1641
1759
  // This includes:
1642
1760
  // - author/timestamp (computed from grouped links)
@@ -2020,7 +2138,7 @@ WHERE ${whereConditions.join(' AND ')}
2020
2138
  // Generate actions from metadata (replaces Prolog query)
2021
2139
  const actions = this.generateCollectionAction(key, 'setter');
2022
2140
 
2023
- if (value) {
2141
+ if (value != null) {
2024
2142
  if (Array.isArray(value)) {
2025
2143
  await this.#perspective.executeAction(
2026
2144
  actions,
@@ -2045,7 +2163,7 @@ WHERE ${whereConditions.join(' AND ')}
2045
2163
  // Generate actions from metadata (replaces Prolog query)
2046
2164
  const actions = this.generateCollectionAction(key, 'adder');
2047
2165
 
2048
- if (value) {
2166
+ if (value != null) {
2049
2167
  if (Array.isArray(value)) {
2050
2168
  await Promise.all(
2051
2169
  value.map((v) =>
@@ -2069,7 +2187,7 @@ WHERE ${whereConditions.join(' AND ')}
2069
2187
  // Generate actions from metadata (replaces Prolog query)
2070
2188
  const actions = this.generateCollectionAction(key, 'remover');
2071
2189
 
2072
- if (value) {
2190
+ if (value != null) {
2073
2191
  if (Array.isArray(value)) {
2074
2192
  await Promise.all(
2075
2193
  value.map((v) =>
@@ -2181,11 +2299,8 @@ WHERE ${whereConditions.join(' AND ')}
2181
2299
  break;
2182
2300
  }
2183
2301
  } else if (Array.isArray(value)) {
2184
- // Handle all arrays as collections, even empty ones
2185
- if (value.length > 0) {
2186
- await this.setCollectionSetter(key, value, batchId);
2187
- }
2188
- // Skip empty arrays - don't try to set them as properties
2302
+ // Handle all arrays as collections, including empty ones (which clears the collection)
2303
+ await this.setCollectionSetter(key, value, batchId);
2189
2304
  } else if (value !== undefined && value !== null && value !== "") {
2190
2305
  if (setProperties) {
2191
2306
  // Check if this is a collection property (has collection metadata)
@@ -50,35 +50,7 @@ export class Subject {
50
50
  Object.defineProperty(this, p, {
51
51
  configurable: true,
52
52
  get: async () => {
53
- // Try Prolog first
54
- try {
55
- let results = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), property_getter(C, "${this.#baseExpression}", "${p}", Value)`)
56
- if(results && results.length > 0 && results[0].Value !== undefined && results[0].Value !== null && results[0].Value !== '') {
57
- let expressionURI = results[0].Value
58
- if(resolveExpressionURI) {
59
- try {
60
- if (expressionURI) {
61
- const expression = await this.#perspective.getExpression(expressionURI)
62
- try {
63
- return JSON.parse(expression.data)
64
- } catch(e) {
65
- return expression.data
66
- }
67
- } else {
68
- return expressionURI
69
- }
70
- } catch (err) {
71
- return expressionURI
72
- }
73
- } else {
74
- return expressionURI
75
- }
76
- }
77
- } catch (err) {
78
- // Prolog query failed, fall through to SurrealDB
79
- }
80
-
81
- // Fallback to SurrealDB if Prolog returned nothing (SdnaOnly mode)
53
+ // Use SurrealDB for data queries
82
54
  try {
83
55
  return await this.#perspective.getPropertyValueViaSurreal(this.#baseExpression, this.#subjectClassName, p);
84
56
  } catch (err) {
@@ -119,20 +91,7 @@ export class Subject {
119
91
  Object.defineProperty(this, c, {
120
92
  configurable: true,
121
93
  get: async () => {
122
- // Try Prolog first
123
- try {
124
- let results = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), collection_getter(C, "${this.#baseExpression}", "${c}", Value)`)
125
- if(results && results.length > 0 && results[0].Value && Array.isArray(results[0].Value) && results[0].Value.length > 0) {
126
- let collectionContent = results[0].Value.filter((v: any) => v !== "" && v !== '')
127
- if (collectionContent.length > 0) {
128
- return collectionContent
129
- }
130
- }
131
- } catch (err) {
132
- // Prolog query failed, fall through to SurrealDB
133
- }
134
-
135
- // Fallback to SurrealDB if Prolog returned nothing (SdnaOnly mode)
94
+ // Use SurrealDB for data queries
136
95
  try {
137
96
  return await this.#perspective.getCollectionValuesViaSurreal(this.#baseExpression, this.#subjectClassName, c);
138
97
  } catch (err) {
@@ -180,6 +180,13 @@ export interface PropertyOptions {
180
180
  */
181
181
  setter?: string;
182
182
 
183
+ /**
184
+ * Custom SurrealQL getter to resolve the property value. Use this for custom graph traversals.
185
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
186
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)[0]"
187
+ */
188
+ surrealGetter?: string;
189
+
183
190
  /**
184
191
  * Indicates whether the property is stored locally in the perspective and not in the network. Useful for properties that are not meant to be shared with the network.
185
192
  */
@@ -412,6 +419,13 @@ export interface CollectionOptions {
412
419
  */
413
420
  where?: WhereOptions;
414
421
 
422
+ /**
423
+ * Custom SurrealQL getter to resolve the collection values. Use this for custom graph traversals.
424
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
425
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)"
426
+ */
427
+ surrealGetter?: string;
428
+
415
429
  /**
416
430
  * Indicates whether the property is stored locally in the perspective and not in the network. Useful for properties that are not meant to be shared with the network.
417
431
  */
@@ -1178,7 +1178,7 @@ export class PerspectiveProxy {
1178
1178
  * Returns required predicates that define what makes something an instance,
1179
1179
  * plus a map of property/collection names to their predicates.
1180
1180
  */
1181
- private async getSubjectClassMetadataFromSDNA(className: string): Promise<{
1181
+ async getSubjectClassMetadataFromSDNA(className: string): Promise<{
1182
1182
  requiredPredicates: string[],
1183
1183
  requiredTriples: Array<{predicate: string, target?: string}>,
1184
1184
  properties: Map<string, { predicate: string, resolveLanguage?: string }>,
@@ -1479,7 +1479,7 @@ export class PerspectiveProxy {
1479
1479
  * Batch-checks multiple expressions against subject class metadata using a single or limited SurrealDB queries.
1480
1480
  * This avoids N+1 query problems by checking all values at once.
1481
1481
  */
1482
- private async batchCheckSubjectInstances(
1482
+ async batchCheckSubjectInstances(
1483
1483
  expressions: string[],
1484
1484
  metadata: {
1485
1485
  requiredPredicates: string[],