@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.
@@ -306,6 +306,13 @@ export class Ad4mModel {
306
306
  }
307
307
  return classCache[perspectiveID];
308
308
  }
309
+ /**
310
+ * Backwards compatibility alias for createdAt.
311
+ * @deprecated Use createdAt instead. This will be removed in a future version.
312
+ */
313
+ get timestamp() {
314
+ return this.createdAt;
315
+ }
309
316
  /**
310
317
  * Extracts metadata from decorators for query building.
311
318
  *
@@ -367,6 +374,7 @@ export class Ad4mModel {
367
374
  ...(options.initial !== undefined && { initial: options.initial }),
368
375
  ...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
369
376
  ...(options.getter !== undefined && { getter: options.getter }),
377
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter }),
370
378
  ...(options.setter !== undefined && { setter: options.setter }),
371
379
  ...(options.local !== undefined && { local: options.local }),
372
380
  ...(options.transform !== undefined && { transform: options.transform }),
@@ -382,7 +390,8 @@ export class Ad4mModel {
382
390
  name: collectionName,
383
391
  predicate: options.through || "",
384
392
  ...(options.where !== undefined && { where: options.where }),
385
- ...(options.local !== undefined && { local: options.local })
393
+ ...(options.local !== undefined && { local: options.local }),
394
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter })
386
395
  };
387
396
  }
388
397
  // Fallback: If both structures are empty but a JSON schema is attached, derive from it
@@ -603,20 +612,30 @@ export class Ad4mModel {
603
612
  `;
604
613
  const links = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").querySurrealDB(linksQuery);
605
614
  if (links && links.length > 0) {
615
+ let minTimestamp = null;
606
616
  let maxTimestamp = null;
607
617
  let latestAuthor = null;
608
- // Process properties
618
+ let originalAuthor = null;
619
+ // Process properties (skip those with surrealGetter)
609
620
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
621
+ if (propMeta.surrealGetter)
622
+ continue; // Handle via surrealGetter evaluation
610
623
  const matching = links.filter((l) => l.predicate === propMeta.predicate);
611
624
  if (matching.length > 0) {
612
625
  // "Latest wins" semantics: select the last element since links are ordered ASC.
613
626
  // The last element has the most recent timestamp and represents the current property value.
614
627
  const link = matching[matching.length - 1];
615
628
  let value = link.target;
616
- // Track timestamp/author
617
- if (link.timestamp && (!maxTimestamp || link.timestamp > maxTimestamp)) {
618
- maxTimestamp = link.timestamp;
619
- latestAuthor = link.author;
629
+ // Track timestamps/authors for createdAt and updatedAt
630
+ if (link.timestamp) {
631
+ if (!minTimestamp || link.timestamp < minTimestamp) {
632
+ minTimestamp = link.timestamp;
633
+ originalAuthor = link.author;
634
+ }
635
+ if (!maxTimestamp || link.timestamp > maxTimestamp) {
636
+ maxTimestamp = link.timestamp;
637
+ latestAuthor = link.author;
638
+ }
620
639
  }
621
640
  // Handle resolveLanguage
622
641
  if (propMeta.resolveLanguage && propMeta.resolveLanguage !== 'literal') {
@@ -652,21 +671,44 @@ export class Ad4mModel {
652
671
  this[propName] = value;
653
672
  }
654
673
  }
655
- // Process collections
674
+ // Process collections (skip those with surrealGetter)
656
675
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
676
+ if (collMeta.surrealGetter)
677
+ continue; // Handle via surrealGetter evaluation
657
678
  const matching = links.filter((l) => l.predicate === collMeta.predicate);
658
679
  // Collections preserve chronological order: links are sorted ASC by timestamp,
659
680
  // so the collection reflects the order in which items were added (oldest to newest).
660
- this[collName] = matching.map((l) => l.target);
681
+ let values = matching.map((l) => l.target);
682
+ // Apply where.isInstance filtering if present
683
+ if (collMeta.where?.isInstance && values.length > 0) {
684
+ try {
685
+ const className = typeof collMeta.where.isInstance === 'string'
686
+ ? collMeta.where.isInstance
687
+ : collMeta.where.isInstance.name;
688
+ const filterMetadata = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").getSubjectClassMetadataFromSDNA(className);
689
+ if (filterMetadata) {
690
+ values = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").batchCheckSubjectInstances(values, filterMetadata);
691
+ }
692
+ }
693
+ catch (error) {
694
+ // Keep unfiltered values on error
695
+ }
696
+ }
697
+ this[collName] = values;
698
+ }
699
+ // Set author and timestamps
700
+ if (originalAuthor) {
701
+ this.author = originalAuthor;
661
702
  }
662
- // Set author and timestamp
663
- if (latestAuthor) {
664
- this.author = latestAuthor;
703
+ if (minTimestamp) {
704
+ this.createdAt = minTimestamp;
665
705
  }
666
706
  if (maxTimestamp) {
667
- this.timestamp = maxTimestamp;
707
+ this.updatedAt = maxTimestamp;
668
708
  }
669
709
  }
710
+ // Evaluate SurrealQL getters
711
+ await ctor.evaluateSurrealGettersForInstance(this, __classPrivateFieldGet(this, _Ad4mModel_perspective, "f"), metadata);
670
712
  }
671
713
  catch (e) {
672
714
  console.error(`SurrealDB getData also failed for ${__classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f")}:`, e);
@@ -695,6 +737,51 @@ export class Ad4mModel {
695
737
  `;
696
738
  return fullQuery;
697
739
  }
740
+ /**
741
+ * Evaluates custom SurrealQL getters for properties and collections on a specific instance.
742
+ * @private
743
+ */
744
+ static async evaluateSurrealGettersForInstance(instance, perspective, metadata) {
745
+ const safeBaseExpression = this.formatSurrealValue(instance.baseExpression);
746
+ // Evaluate property surrealGetters
747
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
748
+ if (propMeta.surrealGetter) {
749
+ try {
750
+ // Replace 'Base' placeholder with actual base expression
751
+ const query = propMeta.surrealGetter.replace(/Base/g, safeBaseExpression);
752
+ // Query from node table to have graph traversal context
753
+ const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
754
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null && result[0].value !== 'None' && result[0].value !== '') {
755
+ instance[propName] = result[0].value;
756
+ }
757
+ }
758
+ catch (error) {
759
+ console.warn(`Failed to evaluate surrealGetter for ${propName}:`, error);
760
+ }
761
+ }
762
+ }
763
+ // Evaluate collection surrealGetters
764
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
765
+ if (collMeta.surrealGetter) {
766
+ try {
767
+ // Replace 'Base' placeholder with actual base expression
768
+ const query = collMeta.surrealGetter.replace(/Base/g, safeBaseExpression);
769
+ // Query from node table to have graph traversal context
770
+ const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
771
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
772
+ // Filter out 'None' from collection results
773
+ const value = result[0].value;
774
+ instance[collName] = Array.isArray(value)
775
+ ? value.filter((v) => v && v !== '' && v !== 'None')
776
+ : value;
777
+ }
778
+ }
779
+ catch (error) {
780
+ console.warn(`Failed to evaluate surrealGetter for ${collName}:`, error);
781
+ }
782
+ }
783
+ }
784
+ }
698
785
  /**
699
786
  * Generates a SurrealQL query from a Query object.
700
787
  *
@@ -1097,8 +1184,9 @@ WHERE ${whereConditions.join(' AND ')}
1097
1184
  fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${escapedPredicate}') AS ${collName}`);
1098
1185
  }
1099
1186
  // Always add author and timestamp fields
1100
- fields.push(`(SELECT VALUE author FROM link WHERE source = source LIMIT 1) AS author`);
1101
- fields.push(`(SELECT VALUE timestamp FROM link WHERE source = source LIMIT 1) AS timestamp`);
1187
+ fields.push(`(SELECT VALUE author FROM link WHERE source = source ORDER BY timestamp ASC LIMIT 1) AS author`);
1188
+ fields.push(`(SELECT VALUE timestamp FROM link WHERE source = source ORDER BY timestamp ASC LIMIT 1) AS createdAt`);
1189
+ fields.push(`(SELECT VALUE timestamp FROM link WHERE source = source ORDER BY timestamp DESC LIMIT 1) AS updatedAt`);
1102
1190
  return fields.join(',\n ');
1103
1191
  }
1104
1192
  /**
@@ -1129,9 +1217,10 @@ WHERE ${whereConditions.join(' AND ')}
1129
1217
  const escapedPredicate = escapeSurrealString(collMeta.predicate);
1130
1218
  fields.push(`target[WHERE predicate = '${escapedPredicate}'] AS ${collName}`);
1131
1219
  }
1132
- // Always add author and timestamp fields using array::first
1220
+ // Always add author and timestamp fields
1133
1221
  fields.push(`array::first(author) AS author`);
1134
- fields.push(`array::first(timestamp) AS timestamp`);
1222
+ fields.push(`array::first(timestamp) AS createdAt`);
1223
+ fields.push(`array::last(timestamp) AS updatedAt`);
1135
1224
  return fields.join(',\n ');
1136
1225
  }
1137
1226
  /**
@@ -1230,8 +1319,10 @@ WHERE ${whereConditions.join(' AND ')}
1230
1319
  }
1231
1320
  const links = row.links || [];
1232
1321
  const instance = new this(perspective, base);
1233
- // Track the most recent timestamp and corresponding author
1322
+ // Track both earliest (createdAt) and most recent (updatedAt) timestamps
1323
+ let minTimestamp = null;
1234
1324
  let maxTimestamp = null;
1325
+ let originalAuthor = null;
1235
1326
  let latestAuthor = null;
1236
1327
  // Process each link (track index for collection ordering)
1237
1328
  for (let linkIndex = 0; linkIndex < links.length; linkIndex++) {
@@ -1241,14 +1332,22 @@ WHERE ${whereConditions.join(' AND ')}
1241
1332
  // Skip 'None' values
1242
1333
  if (target === 'None')
1243
1334
  continue;
1244
- // Track the most recent timestamp and its author
1245
- if (link.timestamp && (!maxTimestamp || link.timestamp > maxTimestamp)) {
1246
- maxTimestamp = link.timestamp;
1247
- latestAuthor = link.author;
1335
+ // Track both earliest (createdAt) and latest (updatedAt) timestamps with their authors
1336
+ if (link.timestamp) {
1337
+ if (!minTimestamp || link.timestamp < minTimestamp) {
1338
+ minTimestamp = link.timestamp;
1339
+ originalAuthor = link.author;
1340
+ }
1341
+ if (!maxTimestamp || link.timestamp > maxTimestamp) {
1342
+ maxTimestamp = link.timestamp;
1343
+ latestAuthor = link.author;
1344
+ }
1248
1345
  }
1249
- // Find matching property
1346
+ // Find matching property (skip those with surrealGetter)
1250
1347
  let foundProperty = false;
1251
1348
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1349
+ if (propMeta.surrealGetter)
1350
+ continue; // Handle via surrealGetter evaluation
1252
1351
  if (propMeta.predicate === predicate) {
1253
1352
  // For properties, take the first value (or we could use timestamp to get latest)
1254
1353
  // Note: Empty objects {} are truthy, so we need to check for them explicitly
@@ -1318,9 +1417,11 @@ WHERE ${whereConditions.join(' AND ')}
1318
1417
  break;
1319
1418
  }
1320
1419
  }
1321
- // If not a property, check if it's a collection
1420
+ // If not a property, check if it's a collection (skip those with surrealGetter)
1322
1421
  if (!foundProperty) {
1323
1422
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1423
+ if (collMeta.surrealGetter)
1424
+ continue; // Handle via surrealGetter evaluation
1324
1425
  if (collMeta.predicate === predicate) {
1325
1426
  // For collections, accumulate all values with their timestamps and indices for sorting
1326
1427
  if (!instance[collName]) {
@@ -1346,20 +1447,34 @@ WHERE ${whereConditions.join(' AND ')}
1346
1447
  }
1347
1448
  }
1348
1449
  }
1349
- // Set author and timestamp from the most recent link
1350
- if (latestAuthor && maxTimestamp) {
1351
- instance.author = latestAuthor;
1352
- // Convert timestamp to number (milliseconds) if it's an ISO string
1450
+ // Set author and timestamps
1451
+ if (originalAuthor) {
1452
+ instance.author = originalAuthor;
1453
+ }
1454
+ // Set createdAt from earliest timestamp
1455
+ if (minTimestamp) {
1456
+ if (typeof minTimestamp === 'string' && minTimestamp.includes('T')) {
1457
+ instance.createdAt = new Date(minTimestamp).getTime();
1458
+ }
1459
+ else if (typeof minTimestamp === 'string') {
1460
+ const parsed = parseInt(minTimestamp, 10);
1461
+ instance.createdAt = isNaN(parsed) ? minTimestamp : parsed;
1462
+ }
1463
+ else {
1464
+ instance.createdAt = minTimestamp;
1465
+ }
1466
+ }
1467
+ // Set updatedAt from most recent timestamp
1468
+ if (maxTimestamp) {
1353
1469
  if (typeof maxTimestamp === 'string' && maxTimestamp.includes('T')) {
1354
- instance.timestamp = new Date(maxTimestamp).getTime();
1470
+ instance.updatedAt = new Date(maxTimestamp).getTime();
1355
1471
  }
1356
1472
  else if (typeof maxTimestamp === 'string') {
1357
- // Try to parse as number string
1358
1473
  const parsed = parseInt(maxTimestamp, 10);
1359
- instance.timestamp = isNaN(parsed) ? maxTimestamp : parsed;
1474
+ instance.updatedAt = isNaN(parsed) ? maxTimestamp : parsed;
1360
1475
  }
1361
1476
  else {
1362
- instance.timestamp = maxTimestamp;
1477
+ instance.updatedAt = maxTimestamp;
1363
1478
  }
1364
1479
  }
1365
1480
  // Sort collections by timestamp to maintain insertion order
@@ -1383,8 +1498,10 @@ WHERE ${whereConditions.join(' AND ')}
1383
1498
  // Use original index as tiebreaker for stable sorting
1384
1499
  return a.originalIndex - b.originalIndex;
1385
1500
  });
1386
- // Replace collection with sorted values
1387
- instance[collName] = pairs.map(p => p.value);
1501
+ // Replace collection with sorted values, filtering out empty strings and None
1502
+ instance[collName] = pairs
1503
+ .map(p => p.value)
1504
+ .filter((v) => v && v !== '' && v !== 'None');
1388
1505
  // Clean up temporary arrays
1389
1506
  delete instance[timestampsKey];
1390
1507
  delete instance[indicesKey];
@@ -1406,6 +1523,40 @@ WHERE ${whereConditions.join(' AND ')}
1406
1523
  console.error(`Failed to process SurrealDB instance ${base}:`, error);
1407
1524
  }
1408
1525
  }
1526
+ // Evaluate SurrealQL getters for all instances
1527
+ for (const instance of instances) {
1528
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
1529
+ }
1530
+ // Filter collections by where.isInstance if specified
1531
+ // Do this for all instances that have collections with filters
1532
+ for (const instance of instances) {
1533
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1534
+ if (collMeta.where?.isInstance && instance[collName]?.length > 0) {
1535
+ try {
1536
+ const targetClass = collMeta.where.isInstance;
1537
+ const subjects = instance[collName];
1538
+ // Get the class metadata from SDNA to pass to batchCheckSubjectInstances
1539
+ const targetClassName = typeof targetClass === 'string'
1540
+ ? targetClass
1541
+ : targetClass.prototype?.className || targetClass.name;
1542
+ const classMetadata = await perspective.getSubjectClassMetadataFromSDNA(targetClassName);
1543
+ if (!classMetadata) {
1544
+ continue;
1545
+ }
1546
+ // Check which subjects are instances of the target class
1547
+ const validSubjects = await perspective.batchCheckSubjectInstances(subjects, classMetadata);
1548
+ instance[collName] = validSubjects;
1549
+ }
1550
+ catch (error) {
1551
+ // On error, leave the collection unfiltered rather than breaking everything
1552
+ }
1553
+ }
1554
+ }
1555
+ }
1556
+ // Evaluate SurrealQL getters for all instances
1557
+ for (const instance of instances) {
1558
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
1559
+ }
1409
1560
  // Filter by where conditions that couldn't be filtered in SQL
1410
1561
  // This includes:
1411
1562
  // - author/timestamp (computed from grouped links)
@@ -86,6 +86,12 @@ export interface PropertyOptions {
86
86
  * Custom setter to set the value of the property in the prolog engine. Only available if the property is writable.
87
87
  */
88
88
  setter?: string;
89
+ /**
90
+ * Custom SurrealQL getter to resolve the property value. Use this for custom graph traversals.
91
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
92
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)[0]"
93
+ */
94
+ surrealGetter?: string;
89
95
  /**
90
96
  * 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.
91
97
  */
@@ -254,6 +260,12 @@ export interface CollectionOptions {
254
260
  * An object representing the WHERE clause of the query.
255
261
  */
256
262
  where?: WhereOptions;
263
+ /**
264
+ * Custom SurrealQL getter to resolve the collection values. Use this for custom graph traversals.
265
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
266
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)"
267
+ */
268
+ surrealGetter?: string;
257
269
  /**
258
270
  * 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.
259
271
  */
@@ -582,7 +582,21 @@ export declare class PerspectiveProxy {
582
582
  * Returns required predicates that define what makes something an instance,
583
583
  * plus a map of property/collection names to their predicates.
584
584
  */
585
- private getSubjectClassMetadataFromSDNA;
585
+ getSubjectClassMetadataFromSDNA(className: string): Promise<{
586
+ requiredPredicates: string[];
587
+ requiredTriples: Array<{
588
+ predicate: string;
589
+ target?: string;
590
+ }>;
591
+ properties: Map<string, {
592
+ predicate: string;
593
+ resolveLanguage?: string;
594
+ }>;
595
+ collections: Map<string, {
596
+ predicate: string;
597
+ instanceFilter?: string;
598
+ }>;
599
+ } | null>;
586
600
  /**
587
601
  * Generates a SurrealDB query to find instances based on class metadata.
588
602
  */
@@ -601,7 +615,21 @@ export declare class PerspectiveProxy {
601
615
  * Batch-checks multiple expressions against subject class metadata using a single or limited SurrealDB queries.
602
616
  * This avoids N+1 query problems by checking all values at once.
603
617
  */
604
- private batchCheckSubjectInstances;
618
+ batchCheckSubjectInstances(expressions: string[], metadata: {
619
+ requiredPredicates: string[];
620
+ requiredTriples: Array<{
621
+ predicate: string;
622
+ target?: string;
623
+ }>;
624
+ properties: Map<string, {
625
+ predicate: string;
626
+ resolveLanguage?: string;
627
+ }>;
628
+ collections: Map<string, {
629
+ predicate: string;
630
+ instanceFilter?: string;
631
+ }>;
632
+ }): Promise<string[]>;
605
633
  /**
606
634
  * Fallback sequential instance checking when batch checking isn't available.
607
635
  */
package/package.json CHANGED
@@ -5,7 +5,6 @@
5
5
  "module": "lib/index.js",
6
6
  "types": "lib/src/index.d.ts",
7
7
  "type": "module",
8
- "private": false,
9
8
  "repository": {
10
9
  "type": "git",
11
10
  "url": "git+https://github.com/coasys/ad4m.git"
@@ -58,7 +57,7 @@
58
57
  "react-dom": "*"
59
58
  },
60
59
  "patchedDependencies": {},
61
- "version": "0.11.2-dev.2",
60
+ "version": "0.11.2-dev.4",
62
61
  "scripts": {
63
62
  "build": "patch-package && tsc && pnpm run buildSchema && pnpm run bundle",
64
63
  "buildSchema": "node --es-module-specifier-resolution=node lib/src/buildSchema.js",