@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.
@@ -367,6 +367,7 @@ export class Ad4mModel {
367
367
  ...(options.initial !== undefined && { initial: options.initial }),
368
368
  ...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
369
369
  ...(options.getter !== undefined && { getter: options.getter }),
370
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter }),
370
371
  ...(options.setter !== undefined && { setter: options.setter }),
371
372
  ...(options.local !== undefined && { local: options.local }),
372
373
  ...(options.transform !== undefined && { transform: options.transform }),
@@ -382,7 +383,8 @@ export class Ad4mModel {
382
383
  name: collectionName,
383
384
  predicate: options.through || "",
384
385
  ...(options.where !== undefined && { where: options.where }),
385
- ...(options.local !== undefined && { local: options.local })
386
+ ...(options.local !== undefined && { local: options.local }),
387
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter })
386
388
  };
387
389
  }
388
390
  // Fallback: If both structures are empty but a JSON schema is attached, derive from it
@@ -489,6 +491,10 @@ export class Ad4mModel {
489
491
  * @private
490
492
  */
491
493
  generatePropertySetterAction(key, metadata) {
494
+ // Check if property is read-only
495
+ if (metadata.writable === false) {
496
+ throw new Error(`Property "${key}" is read-only and cannot be written`);
497
+ }
492
498
  if (metadata.setter) {
493
499
  // Custom setter - throw error for now (Phase 2)
494
500
  throw new Error(`Custom setter for property "${key}" not yet supported without Prolog. ` +
@@ -581,32 +587,16 @@ export class Ad4mModel {
581
587
  }
582
588
  async getData() {
583
589
  // Builds an object with the author, timestamp, all properties, & all collections on the Ad4mModel and saves it to the instance
584
- const subQueries = [buildAuthorAndTimestampQuery(), buildPropertiesQuery(), buildCollectionsQuery()];
585
- const fullQuery = `
586
- Base = "${__classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f")}",
587
- subject_class("${__classPrivateFieldGet(this, _Ad4mModel_subjectClassName, "f")}", SubjectClass),
588
- ${subQueries.join(", ")}
589
- `;
590
- // Try Prolog first
591
- try {
592
- const result = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").infer(fullQuery);
593
- if (result?.[0] && result[0].Properties && result[0].Properties.length > 0) {
594
- const { Properties, Collections, Timestamp, Author } = result[0];
595
- const values = [...Properties, ...Collections, ["timestamp", Timestamp], ["author", Author]];
596
- await Ad4mModel.assignValuesToInstance(__classPrivateFieldGet(this, _Ad4mModel_perspective, "f"), this, values);
597
- return this;
598
- }
599
- }
600
- catch (e) {
601
- console.log(`Prolog getData failed for ${__classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f")}, falling back to SurrealDB`);
602
- }
603
- // Fallback to SurrealDB (SdnaOnly mode)
590
+ // Use SurrealDB for data queries
604
591
  try {
605
592
  const ctor = this.constructor;
606
593
  const metadata = ctor.getModelMetadata();
607
594
  // Query for all links from this specific node (base expression)
608
595
  // Using formatSurrealValue to prevent SQL injection by properly escaping the value
609
596
  const safeBaseExpression = ctor.formatSurrealValue(__classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f"));
597
+ // Note: We use ORDER BY timestamp ASC because:
598
+ // - For collections: we want chronological order (oldest to newest)
599
+ // - For properties: we select the LAST element to get "latest wins" semantics
610
600
  const linksQuery = `
611
601
  SELECT id, predicate, out.uri AS target, author, timestamp
612
602
  FROM link
@@ -617,11 +607,15 @@ export class Ad4mModel {
617
607
  if (links && links.length > 0) {
618
608
  let maxTimestamp = null;
619
609
  let latestAuthor = null;
620
- // Process properties
610
+ // Process properties (skip those with surrealGetter)
621
611
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
612
+ if (propMeta.surrealGetter)
613
+ continue; // Handle via surrealGetter evaluation
622
614
  const matching = links.filter((l) => l.predicate === propMeta.predicate);
623
615
  if (matching.length > 0) {
624
- const link = matching[0]; // Take first/latest
616
+ // "Latest wins" semantics: select the last element since links are ordered ASC.
617
+ // The last element has the most recent timestamp and represents the current property value.
618
+ const link = matching[matching.length - 1];
625
619
  let value = link.target;
626
620
  // Track timestamp/author
627
621
  if (link.timestamp && (!maxTimestamp || link.timestamp > maxTimestamp)) {
@@ -662,11 +656,30 @@ export class Ad4mModel {
662
656
  this[propName] = value;
663
657
  }
664
658
  }
665
- // Process collections
659
+ // Process collections (skip those with surrealGetter)
666
660
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
661
+ if (collMeta.surrealGetter)
662
+ continue; // Handle via surrealGetter evaluation
667
663
  const matching = links.filter((l) => l.predicate === collMeta.predicate);
668
- // Links are already sorted by timestamp ASC from the query, so map preserves order
669
- this[collName] = matching.map((l) => l.target);
664
+ // Collections preserve chronological order: links are sorted ASC by timestamp,
665
+ // so the collection reflects the order in which items were added (oldest to newest).
666
+ let values = matching.map((l) => l.target);
667
+ // Apply where.isInstance filtering if present
668
+ if (collMeta.where?.isInstance && values.length > 0) {
669
+ try {
670
+ const className = typeof collMeta.where.isInstance === 'string'
671
+ ? collMeta.where.isInstance
672
+ : collMeta.where.isInstance.name;
673
+ const filterMetadata = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").getSubjectClassMetadataFromSDNA(className);
674
+ if (filterMetadata) {
675
+ values = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").batchCheckSubjectInstances(values, filterMetadata);
676
+ }
677
+ }
678
+ catch (error) {
679
+ // Keep unfiltered values on error
680
+ }
681
+ }
682
+ this[collName] = values;
670
683
  }
671
684
  // Set author and timestamp
672
685
  if (latestAuthor) {
@@ -676,6 +689,8 @@ export class Ad4mModel {
676
689
  this.timestamp = maxTimestamp;
677
690
  }
678
691
  }
692
+ // Evaluate SurrealQL getters
693
+ await ctor.evaluateSurrealGettersForInstance(this, __classPrivateFieldGet(this, _Ad4mModel_perspective, "f"), metadata);
679
694
  }
680
695
  catch (e) {
681
696
  console.error(`SurrealDB getData also failed for ${__classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f")}:`, e);
@@ -704,6 +719,51 @@ export class Ad4mModel {
704
719
  `;
705
720
  return fullQuery;
706
721
  }
722
+ /**
723
+ * Evaluates custom SurrealQL getters for properties and collections on a specific instance.
724
+ * @private
725
+ */
726
+ static async evaluateSurrealGettersForInstance(instance, perspective, metadata) {
727
+ const safeBaseExpression = this.formatSurrealValue(instance.baseExpression);
728
+ // Evaluate property surrealGetters
729
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
730
+ if (propMeta.surrealGetter) {
731
+ try {
732
+ // Replace 'Base' placeholder with actual base expression
733
+ const query = propMeta.surrealGetter.replace(/Base/g, safeBaseExpression);
734
+ // Query from node table to have graph traversal context
735
+ const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
736
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null && result[0].value !== 'None' && result[0].value !== '') {
737
+ instance[propName] = result[0].value;
738
+ }
739
+ }
740
+ catch (error) {
741
+ console.warn(`Failed to evaluate surrealGetter for ${propName}:`, error);
742
+ }
743
+ }
744
+ }
745
+ // Evaluate collection surrealGetters
746
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
747
+ if (collMeta.surrealGetter) {
748
+ try {
749
+ // Replace 'Base' placeholder with actual base expression
750
+ const query = collMeta.surrealGetter.replace(/Base/g, safeBaseExpression);
751
+ // Query from node table to have graph traversal context
752
+ const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
753
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
754
+ // Filter out 'None' from collection results
755
+ const value = result[0].value;
756
+ instance[collName] = Array.isArray(value)
757
+ ? value.filter((v) => v && v !== '' && v !== 'None')
758
+ : value;
759
+ }
760
+ }
761
+ catch (error) {
762
+ console.warn(`Failed to evaluate surrealGetter for ${collName}:`, error);
763
+ }
764
+ }
765
+ }
766
+ }
707
767
  /**
708
768
  * Generates a SurrealQL query from a Query object.
709
769
  *
@@ -1255,9 +1315,11 @@ WHERE ${whereConditions.join(' AND ')}
1255
1315
  maxTimestamp = link.timestamp;
1256
1316
  latestAuthor = link.author;
1257
1317
  }
1258
- // Find matching property
1318
+ // Find matching property (skip those with surrealGetter)
1259
1319
  let foundProperty = false;
1260
1320
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1321
+ if (propMeta.surrealGetter)
1322
+ continue; // Handle via surrealGetter evaluation
1261
1323
  if (propMeta.predicate === predicate) {
1262
1324
  // For properties, take the first value (or we could use timestamp to get latest)
1263
1325
  // Note: Empty objects {} are truthy, so we need to check for them explicitly
@@ -1327,9 +1389,11 @@ WHERE ${whereConditions.join(' AND ')}
1327
1389
  break;
1328
1390
  }
1329
1391
  }
1330
- // If not a property, check if it's a collection
1392
+ // If not a property, check if it's a collection (skip those with surrealGetter)
1331
1393
  if (!foundProperty) {
1332
1394
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1395
+ if (collMeta.surrealGetter)
1396
+ continue; // Handle via surrealGetter evaluation
1333
1397
  if (collMeta.predicate === predicate) {
1334
1398
  // For collections, accumulate all values with their timestamps and indices for sorting
1335
1399
  if (!instance[collName]) {
@@ -1392,8 +1456,10 @@ WHERE ${whereConditions.join(' AND ')}
1392
1456
  // Use original index as tiebreaker for stable sorting
1393
1457
  return a.originalIndex - b.originalIndex;
1394
1458
  });
1395
- // Replace collection with sorted values
1396
- instance[collName] = pairs.map(p => p.value);
1459
+ // Replace collection with sorted values, filtering out empty strings and None
1460
+ instance[collName] = pairs
1461
+ .map(p => p.value)
1462
+ .filter((v) => v && v !== '' && v !== 'None');
1397
1463
  // Clean up temporary arrays
1398
1464
  delete instance[timestampsKey];
1399
1465
  delete instance[indicesKey];
@@ -1415,6 +1481,40 @@ WHERE ${whereConditions.join(' AND ')}
1415
1481
  console.error(`Failed to process SurrealDB instance ${base}:`, error);
1416
1482
  }
1417
1483
  }
1484
+ // Evaluate SurrealQL getters for all instances
1485
+ for (const instance of instances) {
1486
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
1487
+ }
1488
+ // Filter collections by where.isInstance if specified
1489
+ // Do this for all instances that have collections with filters
1490
+ for (const instance of instances) {
1491
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1492
+ if (collMeta.where?.isInstance && instance[collName]?.length > 0) {
1493
+ try {
1494
+ const targetClass = collMeta.where.isInstance;
1495
+ const subjects = instance[collName];
1496
+ // Get the class metadata from SDNA to pass to batchCheckSubjectInstances
1497
+ const targetClassName = typeof targetClass === 'string'
1498
+ ? targetClass
1499
+ : targetClass.prototype?.className || targetClass.name;
1500
+ const classMetadata = await perspective.getSubjectClassMetadataFromSDNA(targetClassName);
1501
+ if (!classMetadata) {
1502
+ continue;
1503
+ }
1504
+ // Check which subjects are instances of the target class
1505
+ const validSubjects = await perspective.batchCheckSubjectInstances(subjects, classMetadata);
1506
+ instance[collName] = validSubjects;
1507
+ }
1508
+ catch (error) {
1509
+ // On error, leave the collection unfiltered rather than breaking everything
1510
+ }
1511
+ }
1512
+ }
1513
+ }
1514
+ // Evaluate SurrealQL getters for all instances
1515
+ for (const instance of instances) {
1516
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
1517
+ }
1418
1518
  // Filter by where conditions that couldn't be filtered in SQL
1419
1519
  // This includes:
1420
1520
  // - author/timestamp (computed from grouped links)
@@ -1755,7 +1855,7 @@ WHERE ${whereConditions.join(' AND ')}
1755
1855
  }
1756
1856
  // Generate actions from metadata (replaces Prolog query)
1757
1857
  const actions = this.generateCollectionAction(key, 'setter');
1758
- if (value) {
1858
+ if (value != null) {
1759
1859
  if (Array.isArray(value)) {
1760
1860
  await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").executeAction(actions, __classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f"), value.map((v) => ({ name: "value", value: v })), batchId);
1761
1861
  }
@@ -1773,7 +1873,7 @@ WHERE ${whereConditions.join(' AND ')}
1773
1873
  }
1774
1874
  // Generate actions from metadata (replaces Prolog query)
1775
1875
  const actions = this.generateCollectionAction(key, 'adder');
1776
- if (value) {
1876
+ if (value != null) {
1777
1877
  if (Array.isArray(value)) {
1778
1878
  await Promise.all(value.map((v) => __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").executeAction(actions, __classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f"), [{ name: "value", value: v }], batchId)));
1779
1879
  }
@@ -1791,7 +1891,7 @@ WHERE ${whereConditions.join(' AND ')}
1791
1891
  }
1792
1892
  // Generate actions from metadata (replaces Prolog query)
1793
1893
  const actions = this.generateCollectionAction(key, 'remover');
1794
- if (value) {
1894
+ if (value != null) {
1795
1895
  if (Array.isArray(value)) {
1796
1896
  await Promise.all(value.map((v) => __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").executeAction(actions, __classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f"), [{ name: "value", value: v }], batchId)));
1797
1897
  }
@@ -1881,11 +1981,8 @@ WHERE ${whereConditions.join(' AND ')}
1881
1981
  }
1882
1982
  }
1883
1983
  else if (Array.isArray(value)) {
1884
- // Handle all arrays as collections, even empty ones
1885
- if (value.length > 0) {
1886
- await this.setCollectionSetter(key, value, batchId);
1887
- }
1888
- // Skip empty arrays - don't try to set them as properties
1984
+ // Handle all arrays as collections, including empty ones (which clears the collection)
1985
+ await this.setCollectionSetter(key, value, batchId);
1889
1986
  }
1890
1987
  else if (value !== undefined && value !== null && value !== "") {
1891
1988
  if (setProperties) {
@@ -55,39 +55,7 @@ export class Subject {
55
55
  Object.defineProperty(this, p, {
56
56
  configurable: true,
57
57
  get: async () => {
58
- // Try Prolog first
59
- try {
60
- let results = await __classPrivateFieldGet(this, _Subject_perspective, "f").infer(`subject_class("${__classPrivateFieldGet(this, _Subject_subjectClassName, "f")}", C), property_getter(C, "${__classPrivateFieldGet(this, _Subject_baseExpression, "f")}", "${p}", Value)`);
61
- if (results && results.length > 0 && results[0].Value !== undefined && results[0].Value !== null && results[0].Value !== '') {
62
- let expressionURI = results[0].Value;
63
- if (resolveExpressionURI) {
64
- try {
65
- if (expressionURI) {
66
- const expression = await __classPrivateFieldGet(this, _Subject_perspective, "f").getExpression(expressionURI);
67
- try {
68
- return JSON.parse(expression.data);
69
- }
70
- catch (e) {
71
- return expression.data;
72
- }
73
- }
74
- else {
75
- return expressionURI;
76
- }
77
- }
78
- catch (err) {
79
- return expressionURI;
80
- }
81
- }
82
- else {
83
- return expressionURI;
84
- }
85
- }
86
- }
87
- catch (err) {
88
- // Prolog query failed, fall through to SurrealDB
89
- }
90
- // Fallback to SurrealDB if Prolog returned nothing (SdnaOnly mode)
58
+ // Use SurrealDB for data queries
91
59
  try {
92
60
  return await __classPrivateFieldGet(this, _Subject_perspective, "f").getPropertyValueViaSurreal(__classPrivateFieldGet(this, _Subject_baseExpression, "f"), __classPrivateFieldGet(this, _Subject_subjectClassName, "f"), p);
93
61
  }
@@ -126,20 +94,7 @@ export class Subject {
126
94
  Object.defineProperty(this, c, {
127
95
  configurable: true,
128
96
  get: async () => {
129
- // Try Prolog first
130
- try {
131
- let results = await __classPrivateFieldGet(this, _Subject_perspective, "f").infer(`subject_class("${__classPrivateFieldGet(this, _Subject_subjectClassName, "f")}", C), collection_getter(C, "${__classPrivateFieldGet(this, _Subject_baseExpression, "f")}", "${c}", Value)`);
132
- if (results && results.length > 0 && results[0].Value && Array.isArray(results[0].Value) && results[0].Value.length > 0) {
133
- let collectionContent = results[0].Value.filter((v) => v !== "" && v !== '');
134
- if (collectionContent.length > 0) {
135
- return collectionContent;
136
- }
137
- }
138
- }
139
- catch (err) {
140
- // Prolog query failed, fall through to SurrealDB
141
- }
142
- // Fallback to SurrealDB if Prolog returned nothing (SdnaOnly mode)
97
+ // Use SurrealDB for data queries
143
98
  try {
144
99
  return await __classPrivateFieldGet(this, _Subject_perspective, "f").getCollectionValuesViaSurreal(__classPrivateFieldGet(this, _Subject_baseExpression, "f"), __classPrivateFieldGet(this, _Subject_subjectClassName, "f"), c);
145
100
  }
@@ -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,13 +5,6 @@
5
5
  "module": "lib/index.js",
6
6
  "types": "lib/src/index.d.ts",
7
7
  "type": "module",
8
-
9
- "scripts": {
10
- "build": "patch-package && tsc && pnpm run buildSchema && pnpm run bundle",
11
- "buildSchema": "node --es-module-specifier-resolution=node lib/src/buildSchema.js",
12
- "bundle": "rollup -c rollup.config.js",
13
- "test": "jest --forceExit"
14
- },
15
8
  "repository": {
16
9
  "type": "git",
17
10
  "url": "git+https://github.com/coasys/ad4m.git"
@@ -64,10 +57,11 @@
64
57
  "react-dom": "*"
65
58
  },
66
59
  "patchedDependencies": {},
67
- "pnpm": {
68
- "patchedDependencies": {
69
- "graphql@15.7.2": "patches/graphql@15.7.2.patch"
70
- }
71
- },
72
- "version": "0.11.2-dev-sdna-only-prolog-2"
73
- }
60
+ "version": "0.11.2-dev.3",
61
+ "scripts": {
62
+ "build": "patch-package && tsc && pnpm run buildSchema && pnpm run bundle",
63
+ "buildSchema": "node --es-module-specifier-resolution=node lib/src/buildSchema.js",
64
+ "bundle": "rollup -c rollup.config.js",
65
+ "test": "jest --forceExit"
66
+ }
67
+ }