@coasys/ad4m 0.11.2-dev.2 → 0.11.2-dev.4

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
  }
@@ -409,7 +413,8 @@ export class Ad4mModel {
409
413
  #source: string;
410
414
  #perspective: PerspectiveProxy;
411
415
  author: string;
412
- timestamp: string;
416
+ createdAt: any;
417
+ updatedAt: any;
413
418
 
414
419
  private static classNamesByClass = new WeakMap<typeof Ad4mModel, { [perspectiveId: string]: string }>();
415
420
 
@@ -438,6 +443,14 @@ export class Ad4mModel {
438
443
  return classCache[perspectiveID];
439
444
  }
440
445
 
446
+ /**
447
+ * Backwards compatibility alias for createdAt.
448
+ * @deprecated Use createdAt instead. This will be removed in a future version.
449
+ */
450
+ get timestamp(): any {
451
+ return (this as any).createdAt;
452
+ }
453
+
441
454
  /**
442
455
  * Extracts metadata from decorators for query building.
443
456
  *
@@ -503,6 +516,7 @@ export class Ad4mModel {
503
516
  ...(options.initial !== undefined && { initial: options.initial }),
504
517
  ...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
505
518
  ...(options.getter !== undefined && { getter: options.getter }),
519
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter }),
506
520
  ...(options.setter !== undefined && { setter: options.setter }),
507
521
  ...(options.local !== undefined && { local: options.local }),
508
522
  ...(options.transform !== undefined && { transform: options.transform }),
@@ -520,7 +534,8 @@ export class Ad4mModel {
520
534
  name: collectionName,
521
535
  predicate: options.through || "",
522
536
  ...(options.where !== undefined && { where: options.where }),
523
- ...(options.local !== undefined && { local: options.local })
537
+ ...(options.local !== undefined && { local: options.local }),
538
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter })
524
539
  };
525
540
  }
526
541
 
@@ -769,11 +784,14 @@ export class Ad4mModel {
769
784
  const links = await this.#perspective.querySurrealDB(linksQuery);
770
785
 
771
786
  if (links && links.length > 0) {
787
+ let minTimestamp = null;
772
788
  let maxTimestamp = null;
773
789
  let latestAuthor = null;
790
+ let originalAuthor = null;
774
791
 
775
- // Process properties
792
+ // Process properties (skip those with surrealGetter)
776
793
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
794
+ if (propMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
777
795
  const matching = links.filter((l: any) => l.predicate === propMeta.predicate);
778
796
  if (matching.length > 0) {
779
797
  // "Latest wins" semantics: select the last element since links are ordered ASC.
@@ -781,10 +799,16 @@ export class Ad4mModel {
781
799
  const link = matching[matching.length - 1];
782
800
  let value = link.target;
783
801
 
784
- // Track timestamp/author
785
- if (link.timestamp && (!maxTimestamp || link.timestamp > maxTimestamp)) {
786
- maxTimestamp = link.timestamp;
787
- latestAuthor = link.author;
802
+ // Track timestamps/authors for createdAt and updatedAt
803
+ if (link.timestamp) {
804
+ if (!minTimestamp || link.timestamp < minTimestamp) {
805
+ minTimestamp = link.timestamp;
806
+ originalAuthor = link.author;
807
+ }
808
+ if (!maxTimestamp || link.timestamp > maxTimestamp) {
809
+ maxTimestamp = link.timestamp;
810
+ latestAuthor = link.author;
811
+ }
788
812
  }
789
813
 
790
814
  // Handle resolveLanguage
@@ -820,22 +844,47 @@ export class Ad4mModel {
820
844
  }
821
845
  }
822
846
 
823
- // Process collections
847
+ // Process collections (skip those with surrealGetter)
824
848
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
849
+ if (collMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
825
850
  const matching = links.filter((l: any) => l.predicate === collMeta.predicate);
826
851
  // Collections preserve chronological order: links are sorted ASC by timestamp,
827
852
  // so the collection reflects the order in which items were added (oldest to newest).
828
- (this as any)[collName] = matching.map((l: any) => l.target);
853
+ let values = matching.map((l: any) => l.target);
854
+
855
+ // Apply where.isInstance filtering if present
856
+ if (collMeta.where?.isInstance && values.length > 0) {
857
+ try {
858
+ const className = typeof collMeta.where.isInstance === 'string'
859
+ ? collMeta.where.isInstance
860
+ : collMeta.where.isInstance.name;
861
+
862
+ const filterMetadata = await this.#perspective.getSubjectClassMetadataFromSDNA(className);
863
+ if (filterMetadata) {
864
+ values = await this.#perspective.batchCheckSubjectInstances(values, filterMetadata);
865
+ }
866
+ } catch (error) {
867
+ // Keep unfiltered values on error
868
+ }
869
+ }
870
+
871
+ (this as any)[collName] = values;
829
872
  }
830
873
 
831
- // Set author and timestamp
832
- if (latestAuthor) {
833
- (this as any).author = latestAuthor;
874
+ // Set author and timestamps
875
+ if (originalAuthor) {
876
+ (this as any).author = originalAuthor;
877
+ }
878
+ if (minTimestamp) {
879
+ (this as any).createdAt = minTimestamp;
834
880
  }
835
881
  if (maxTimestamp) {
836
- (this as any).timestamp = maxTimestamp;
882
+ (this as any).updatedAt = maxTimestamp;
837
883
  }
838
884
  }
885
+
886
+ // Evaluate SurrealQL getters
887
+ await ctor.evaluateSurrealGettersForInstance(this, this.#perspective, metadata);
839
888
  } catch (e) {
840
889
  console.error(`SurrealDB getData also failed for ${this.#baseExpression}:`, e);
841
890
  }
@@ -870,6 +919,60 @@ export class Ad4mModel {
870
919
  return fullQuery;
871
920
  }
872
921
 
922
+ /**
923
+ * Evaluates custom SurrealQL getters for properties and collections on a specific instance.
924
+ * @private
925
+ */
926
+ private static async evaluateSurrealGettersForInstance(
927
+ instance: any,
928
+ perspective: PerspectiveProxy,
929
+ metadata: any
930
+ ) {
931
+ const safeBaseExpression = this.formatSurrealValue(instance.baseExpression);
932
+
933
+ // Evaluate property surrealGetters
934
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
935
+ if ((propMeta as any).surrealGetter) {
936
+ try {
937
+ // Replace 'Base' placeholder with actual base expression
938
+ const query = (propMeta as any).surrealGetter.replace(/Base/g, safeBaseExpression);
939
+ // Query from node table to have graph traversal context
940
+ const result = await perspective.querySurrealDB(
941
+ `SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`
942
+ );
943
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null && result[0].value !== 'None' && result[0].value !== '') {
944
+ instance[propName] = result[0].value;
945
+ }
946
+ } catch (error) {
947
+ console.warn(`Failed to evaluate surrealGetter for ${propName}:`, error);
948
+ }
949
+ }
950
+ }
951
+
952
+ // Evaluate collection surrealGetters
953
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
954
+ if ((collMeta as any).surrealGetter) {
955
+ try {
956
+ // Replace 'Base' placeholder with actual base expression
957
+ const query = (collMeta as any).surrealGetter.replace(/Base/g, safeBaseExpression);
958
+ // Query from node table to have graph traversal context
959
+ const result = await perspective.querySurrealDB(
960
+ `SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`
961
+ );
962
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
963
+ // Filter out 'None' from collection results
964
+ const value = result[0].value;
965
+ instance[collName] = Array.isArray(value)
966
+ ? value.filter((v: any) => v && v !== '' && v !== 'None')
967
+ : value;
968
+ }
969
+ } catch (error) {
970
+ console.warn(`Failed to evaluate surrealGetter for ${collName}:`, error);
971
+ }
972
+ }
973
+ }
974
+ }
975
+
873
976
  /**
874
977
  * Generates a SurrealQL query from a Query object.
875
978
  *
@@ -1295,8 +1398,9 @@ WHERE ${whereConditions.join(' AND ')}
1295
1398
  }
1296
1399
 
1297
1400
  // Always add author and timestamp fields
1298
- fields.push(`(SELECT VALUE author FROM link WHERE source = source LIMIT 1) AS author`);
1299
- fields.push(`(SELECT VALUE timestamp FROM link WHERE source = source LIMIT 1) AS timestamp`);
1401
+ fields.push(`(SELECT VALUE author FROM link WHERE source = source ORDER BY timestamp ASC LIMIT 1) AS author`);
1402
+ fields.push(`(SELECT VALUE timestamp FROM link WHERE source = source ORDER BY timestamp ASC LIMIT 1) AS createdAt`);
1403
+ fields.push(`(SELECT VALUE timestamp FROM link WHERE source = source ORDER BY timestamp DESC LIMIT 1) AS updatedAt`);
1300
1404
 
1301
1405
  return fields.join(',\n ');
1302
1406
  }
@@ -1332,9 +1436,10 @@ WHERE ${whereConditions.join(' AND ')}
1332
1436
  fields.push(`target[WHERE predicate = '${escapedPredicate}'] AS ${collName}`);
1333
1437
  }
1334
1438
 
1335
- // Always add author and timestamp fields using array::first
1439
+ // Always add author and timestamp fields
1336
1440
  fields.push(`array::first(author) AS author`);
1337
- fields.push(`array::first(timestamp) AS timestamp`);
1441
+ fields.push(`array::first(timestamp) AS createdAt`);
1442
+ fields.push(`array::last(timestamp) AS updatedAt`);
1338
1443
 
1339
1444
  return fields.join(',\n ');
1340
1445
  }
@@ -1451,8 +1556,10 @@ WHERE ${whereConditions.join(' AND ')}
1451
1556
 
1452
1557
  const instance = new this(perspective, base) as any;
1453
1558
 
1454
- // Track the most recent timestamp and corresponding author
1559
+ // Track both earliest (createdAt) and most recent (updatedAt) timestamps
1560
+ let minTimestamp = null;
1455
1561
  let maxTimestamp = null;
1562
+ let originalAuthor = null;
1456
1563
  let latestAuthor = null;
1457
1564
 
1458
1565
  // Process each link (track index for collection ordering)
@@ -1464,15 +1571,22 @@ WHERE ${whereConditions.join(' AND ')}
1464
1571
  // Skip 'None' values
1465
1572
  if (target === 'None') continue;
1466
1573
 
1467
- // Track the most recent timestamp and its author
1468
- if (link.timestamp && (!maxTimestamp || link.timestamp > maxTimestamp)) {
1469
- maxTimestamp = link.timestamp;
1470
- latestAuthor = link.author;
1574
+ // Track both earliest (createdAt) and latest (updatedAt) timestamps with their authors
1575
+ if (link.timestamp) {
1576
+ if (!minTimestamp || link.timestamp < minTimestamp) {
1577
+ minTimestamp = link.timestamp;
1578
+ originalAuthor = link.author;
1579
+ }
1580
+ if (!maxTimestamp || link.timestamp > maxTimestamp) {
1581
+ maxTimestamp = link.timestamp;
1582
+ latestAuthor = link.author;
1583
+ }
1471
1584
  }
1472
1585
 
1473
- // Find matching property
1586
+ // Find matching property (skip those with surrealGetter)
1474
1587
  let foundProperty = false;
1475
1588
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1589
+ if (propMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
1476
1590
  if (propMeta.predicate === predicate) {
1477
1591
  // For properties, take the first value (or we could use timestamp to get latest)
1478
1592
  // Note: Empty objects {} are truthy, so we need to check for them explicitly
@@ -1539,9 +1653,10 @@ WHERE ${whereConditions.join(' AND ')}
1539
1653
  }
1540
1654
  }
1541
1655
 
1542
- // If not a property, check if it's a collection
1656
+ // If not a property, check if it's a collection (skip those with surrealGetter)
1543
1657
  if (!foundProperty) {
1544
1658
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1659
+ if (collMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
1545
1660
  if (collMeta.predicate === predicate) {
1546
1661
  // For collections, accumulate all values with their timestamps and indices for sorting
1547
1662
  if (!instance[collName]) {
@@ -1568,18 +1683,32 @@ WHERE ${whereConditions.join(' AND ')}
1568
1683
  }
1569
1684
  }
1570
1685
 
1571
- // Set author and timestamp from the most recent link
1572
- if (latestAuthor && maxTimestamp) {
1573
- instance.author = latestAuthor;
1574
- // Convert timestamp to number (milliseconds) if it's an ISO string
1686
+ // Set author and timestamps
1687
+ if (originalAuthor) {
1688
+ instance.author = originalAuthor;
1689
+ }
1690
+
1691
+ // Set createdAt from earliest timestamp
1692
+ if (minTimestamp) {
1693
+ if (typeof minTimestamp === 'string' && minTimestamp.includes('T')) {
1694
+ instance.createdAt = new Date(minTimestamp).getTime();
1695
+ } else if (typeof minTimestamp === 'string') {
1696
+ const parsed = parseInt(minTimestamp, 10);
1697
+ instance.createdAt = isNaN(parsed) ? minTimestamp : parsed;
1698
+ } else {
1699
+ instance.createdAt = minTimestamp;
1700
+ }
1701
+ }
1702
+
1703
+ // Set updatedAt from most recent timestamp
1704
+ if (maxTimestamp) {
1575
1705
  if (typeof maxTimestamp === 'string' && maxTimestamp.includes('T')) {
1576
- instance.timestamp = new Date(maxTimestamp).getTime();
1706
+ instance.updatedAt = new Date(maxTimestamp).getTime();
1577
1707
  } else if (typeof maxTimestamp === 'string') {
1578
- // Try to parse as number string
1579
1708
  const parsed = parseInt(maxTimestamp, 10);
1580
- instance.timestamp = isNaN(parsed) ? maxTimestamp : parsed;
1709
+ instance.updatedAt = isNaN(parsed) ? maxTimestamp : parsed;
1581
1710
  } else {
1582
- instance.timestamp = maxTimestamp;
1711
+ instance.updatedAt = maxTimestamp;
1583
1712
  }
1584
1713
  }
1585
1714
 
@@ -1603,8 +1732,10 @@ WHERE ${whereConditions.join(' AND ')}
1603
1732
  // Use original index as tiebreaker for stable sorting
1604
1733
  return a.originalIndex - b.originalIndex;
1605
1734
  });
1606
- // Replace collection with sorted values
1607
- instance[collName] = pairs.map(p => p.value);
1735
+ // Replace collection with sorted values, filtering out empty strings and None
1736
+ instance[collName] = pairs
1737
+ .map(p => p.value)
1738
+ .filter((v: any) => v && v !== '' && v !== 'None');
1608
1739
  // Clean up temporary arrays
1609
1740
  delete instance[timestampsKey];
1610
1741
  delete instance[indicesKey];
@@ -1628,6 +1759,46 @@ WHERE ${whereConditions.join(' AND ')}
1628
1759
  }
1629
1760
  }
1630
1761
 
1762
+ // Evaluate SurrealQL getters for all instances
1763
+ for (const instance of instances) {
1764
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
1765
+ }
1766
+
1767
+ // Filter collections by where.isInstance if specified
1768
+ // Do this for all instances that have collections with filters
1769
+ for (const instance of instances) {
1770
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1771
+ if (collMeta.where?.isInstance && instance[collName]?.length > 0) {
1772
+ try {
1773
+ const targetClass = collMeta.where.isInstance;
1774
+ const subjects = instance[collName];
1775
+
1776
+ // Get the class metadata from SDNA to pass to batchCheckSubjectInstances
1777
+ const targetClassName = typeof targetClass === 'string'
1778
+ ? targetClass
1779
+ : (targetClass as any).prototype?.className || targetClass.name;
1780
+ const classMetadata = await perspective.getSubjectClassMetadataFromSDNA(targetClassName);
1781
+
1782
+ if (!classMetadata) {
1783
+ continue;
1784
+ }
1785
+
1786
+ // Check which subjects are instances of the target class
1787
+ const validSubjects = await perspective.batchCheckSubjectInstances(subjects, classMetadata);
1788
+
1789
+ instance[collName] = validSubjects;
1790
+ } catch (error) {
1791
+ // On error, leave the collection unfiltered rather than breaking everything
1792
+ }
1793
+ }
1794
+ }
1795
+ }
1796
+
1797
+ // Evaluate SurrealQL getters for all instances
1798
+ for (const instance of instances) {
1799
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
1800
+ }
1801
+
1631
1802
  // Filter by where conditions that couldn't be filtered in SQL
1632
1803
  // This includes:
1633
1804
  // - author/timestamp (computed from grouped links)
@@ -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[],