@coasys/ad4m 0.11.2-dev.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.
package/lib/index.cjs CHANGED
@@ -18916,6 +18916,7 @@ class Ad4mModel {
18916
18916
  ...(options.initial !== undefined && { initial: options.initial }),
18917
18917
  ...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
18918
18918
  ...(options.getter !== undefined && { getter: options.getter }),
18919
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter }),
18919
18920
  ...(options.setter !== undefined && { setter: options.setter }),
18920
18921
  ...(options.local !== undefined && { local: options.local }),
18921
18922
  ...(options.transform !== undefined && { transform: options.transform }),
@@ -18931,7 +18932,8 @@ class Ad4mModel {
18931
18932
  name: collectionName,
18932
18933
  predicate: options.through || "",
18933
18934
  ...(options.where !== undefined && { where: options.where }),
18934
- ...(options.local !== undefined && { local: options.local })
18935
+ ...(options.local !== undefined && { local: options.local }),
18936
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter })
18935
18937
  };
18936
18938
  }
18937
18939
  // Fallback: If both structures are empty but a JSON schema is attached, derive from it
@@ -19154,8 +19156,10 @@ class Ad4mModel {
19154
19156
  if (links && links.length > 0) {
19155
19157
  let maxTimestamp = null;
19156
19158
  let latestAuthor = null;
19157
- // Process properties
19159
+ // Process properties (skip those with surrealGetter)
19158
19160
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
19161
+ if (propMeta.surrealGetter)
19162
+ continue; // Handle via surrealGetter evaluation
19159
19163
  const matching = links.filter((l) => l.predicate === propMeta.predicate);
19160
19164
  if (matching.length > 0) {
19161
19165
  // "Latest wins" semantics: select the last element since links are ordered ASC.
@@ -19201,12 +19205,30 @@ class Ad4mModel {
19201
19205
  this[propName] = value;
19202
19206
  }
19203
19207
  }
19204
- // Process collections
19208
+ // Process collections (skip those with surrealGetter)
19205
19209
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
19210
+ if (collMeta.surrealGetter)
19211
+ continue; // Handle via surrealGetter evaluation
19206
19212
  const matching = links.filter((l) => l.predicate === collMeta.predicate);
19207
19213
  // Collections preserve chronological order: links are sorted ASC by timestamp,
19208
19214
  // so the collection reflects the order in which items were added (oldest to newest).
19209
- this[collName] = matching.map((l) => l.target);
19215
+ let values = matching.map((l) => l.target);
19216
+ // Apply where.isInstance filtering if present
19217
+ if (collMeta.where?.isInstance && values.length > 0) {
19218
+ try {
19219
+ const className = typeof collMeta.where.isInstance === 'string'
19220
+ ? collMeta.where.isInstance
19221
+ : collMeta.where.isInstance.name;
19222
+ const filterMetadata = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").getSubjectClassMetadataFromSDNA(className);
19223
+ if (filterMetadata) {
19224
+ values = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").batchCheckSubjectInstances(values, filterMetadata);
19225
+ }
19226
+ }
19227
+ catch (error) {
19228
+ // Keep unfiltered values on error
19229
+ }
19230
+ }
19231
+ this[collName] = values;
19210
19232
  }
19211
19233
  // Set author and timestamp
19212
19234
  if (latestAuthor) {
@@ -19216,6 +19238,8 @@ class Ad4mModel {
19216
19238
  this.timestamp = maxTimestamp;
19217
19239
  }
19218
19240
  }
19241
+ // Evaluate SurrealQL getters
19242
+ await ctor.evaluateSurrealGettersForInstance(this, __classPrivateFieldGet(this, _Ad4mModel_perspective, "f"), metadata);
19219
19243
  }
19220
19244
  catch (e) {
19221
19245
  console.error(`SurrealDB getData also failed for ${__classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f")}:`, e);
@@ -19244,6 +19268,51 @@ class Ad4mModel {
19244
19268
  `;
19245
19269
  return fullQuery;
19246
19270
  }
19271
+ /**
19272
+ * Evaluates custom SurrealQL getters for properties and collections on a specific instance.
19273
+ * @private
19274
+ */
19275
+ static async evaluateSurrealGettersForInstance(instance, perspective, metadata) {
19276
+ const safeBaseExpression = this.formatSurrealValue(instance.baseExpression);
19277
+ // Evaluate property surrealGetters
19278
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
19279
+ if (propMeta.surrealGetter) {
19280
+ try {
19281
+ // Replace 'Base' placeholder with actual base expression
19282
+ const query = propMeta.surrealGetter.replace(/Base/g, safeBaseExpression);
19283
+ // Query from node table to have graph traversal context
19284
+ const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
19285
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null && result[0].value !== 'None' && result[0].value !== '') {
19286
+ instance[propName] = result[0].value;
19287
+ }
19288
+ }
19289
+ catch (error) {
19290
+ console.warn(`Failed to evaluate surrealGetter for ${propName}:`, error);
19291
+ }
19292
+ }
19293
+ }
19294
+ // Evaluate collection surrealGetters
19295
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
19296
+ if (collMeta.surrealGetter) {
19297
+ try {
19298
+ // Replace 'Base' placeholder with actual base expression
19299
+ const query = collMeta.surrealGetter.replace(/Base/g, safeBaseExpression);
19300
+ // Query from node table to have graph traversal context
19301
+ const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
19302
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
19303
+ // Filter out 'None' from collection results
19304
+ const value = result[0].value;
19305
+ instance[collName] = Array.isArray(value)
19306
+ ? value.filter((v) => v && v !== '' && v !== 'None')
19307
+ : value;
19308
+ }
19309
+ }
19310
+ catch (error) {
19311
+ console.warn(`Failed to evaluate surrealGetter for ${collName}:`, error);
19312
+ }
19313
+ }
19314
+ }
19315
+ }
19247
19316
  /**
19248
19317
  * Generates a SurrealQL query from a Query object.
19249
19318
  *
@@ -19795,9 +19864,11 @@ WHERE ${whereConditions.join(' AND ')}
19795
19864
  maxTimestamp = link.timestamp;
19796
19865
  latestAuthor = link.author;
19797
19866
  }
19798
- // Find matching property
19867
+ // Find matching property (skip those with surrealGetter)
19799
19868
  let foundProperty = false;
19800
19869
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
19870
+ if (propMeta.surrealGetter)
19871
+ continue; // Handle via surrealGetter evaluation
19801
19872
  if (propMeta.predicate === predicate) {
19802
19873
  // For properties, take the first value (or we could use timestamp to get latest)
19803
19874
  // Note: Empty objects {} are truthy, so we need to check for them explicitly
@@ -19867,9 +19938,11 @@ WHERE ${whereConditions.join(' AND ')}
19867
19938
  break;
19868
19939
  }
19869
19940
  }
19870
- // If not a property, check if it's a collection
19941
+ // If not a property, check if it's a collection (skip those with surrealGetter)
19871
19942
  if (!foundProperty) {
19872
19943
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
19944
+ if (collMeta.surrealGetter)
19945
+ continue; // Handle via surrealGetter evaluation
19873
19946
  if (collMeta.predicate === predicate) {
19874
19947
  // For collections, accumulate all values with their timestamps and indices for sorting
19875
19948
  if (!instance[collName]) {
@@ -19932,8 +20005,10 @@ WHERE ${whereConditions.join(' AND ')}
19932
20005
  // Use original index as tiebreaker for stable sorting
19933
20006
  return a.originalIndex - b.originalIndex;
19934
20007
  });
19935
- // Replace collection with sorted values
19936
- instance[collName] = pairs.map(p => p.value);
20008
+ // Replace collection with sorted values, filtering out empty strings and None
20009
+ instance[collName] = pairs
20010
+ .map(p => p.value)
20011
+ .filter((v) => v && v !== '' && v !== 'None');
19937
20012
  // Clean up temporary arrays
19938
20013
  delete instance[timestampsKey];
19939
20014
  delete instance[indicesKey];
@@ -19955,6 +20030,40 @@ WHERE ${whereConditions.join(' AND ')}
19955
20030
  console.error(`Failed to process SurrealDB instance ${base}:`, error);
19956
20031
  }
19957
20032
  }
20033
+ // Evaluate SurrealQL getters for all instances
20034
+ for (const instance of instances) {
20035
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
20036
+ }
20037
+ // Filter collections by where.isInstance if specified
20038
+ // Do this for all instances that have collections with filters
20039
+ for (const instance of instances) {
20040
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
20041
+ if (collMeta.where?.isInstance && instance[collName]?.length > 0) {
20042
+ try {
20043
+ const targetClass = collMeta.where.isInstance;
20044
+ const subjects = instance[collName];
20045
+ // Get the class metadata from SDNA to pass to batchCheckSubjectInstances
20046
+ const targetClassName = typeof targetClass === 'string'
20047
+ ? targetClass
20048
+ : targetClass.prototype?.className || targetClass.name;
20049
+ const classMetadata = await perspective.getSubjectClassMetadataFromSDNA(targetClassName);
20050
+ if (!classMetadata) {
20051
+ continue;
20052
+ }
20053
+ // Check which subjects are instances of the target class
20054
+ const validSubjects = await perspective.batchCheckSubjectInstances(subjects, classMetadata);
20055
+ instance[collName] = validSubjects;
20056
+ }
20057
+ catch (error) {
20058
+ // On error, leave the collection unfiltered rather than breaking everything
20059
+ }
20060
+ }
20061
+ }
20062
+ }
20063
+ // Evaluate SurrealQL getters for all instances
20064
+ for (const instance of instances) {
20065
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
20066
+ }
19958
20067
  // Filter by where conditions that couldn't be filtered in SQL
19959
20068
  // This includes:
19960
20069
  // - author/timestamp (computed from grouped links)
package/lib/index.js CHANGED
@@ -18912,6 +18912,7 @@ class Ad4mModel {
18912
18912
  ...(options.initial !== undefined && { initial: options.initial }),
18913
18913
  ...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
18914
18914
  ...(options.getter !== undefined && { getter: options.getter }),
18915
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter }),
18915
18916
  ...(options.setter !== undefined && { setter: options.setter }),
18916
18917
  ...(options.local !== undefined && { local: options.local }),
18917
18918
  ...(options.transform !== undefined && { transform: options.transform }),
@@ -18927,7 +18928,8 @@ class Ad4mModel {
18927
18928
  name: collectionName,
18928
18929
  predicate: options.through || "",
18929
18930
  ...(options.where !== undefined && { where: options.where }),
18930
- ...(options.local !== undefined && { local: options.local })
18931
+ ...(options.local !== undefined && { local: options.local }),
18932
+ ...(options.surrealGetter !== undefined && { surrealGetter: options.surrealGetter })
18931
18933
  };
18932
18934
  }
18933
18935
  // Fallback: If both structures are empty but a JSON schema is attached, derive from it
@@ -19150,8 +19152,10 @@ class Ad4mModel {
19150
19152
  if (links && links.length > 0) {
19151
19153
  let maxTimestamp = null;
19152
19154
  let latestAuthor = null;
19153
- // Process properties
19155
+ // Process properties (skip those with surrealGetter)
19154
19156
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
19157
+ if (propMeta.surrealGetter)
19158
+ continue; // Handle via surrealGetter evaluation
19155
19159
  const matching = links.filter((l) => l.predicate === propMeta.predicate);
19156
19160
  if (matching.length > 0) {
19157
19161
  // "Latest wins" semantics: select the last element since links are ordered ASC.
@@ -19197,12 +19201,30 @@ class Ad4mModel {
19197
19201
  this[propName] = value;
19198
19202
  }
19199
19203
  }
19200
- // Process collections
19204
+ // Process collections (skip those with surrealGetter)
19201
19205
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
19206
+ if (collMeta.surrealGetter)
19207
+ continue; // Handle via surrealGetter evaluation
19202
19208
  const matching = links.filter((l) => l.predicate === collMeta.predicate);
19203
19209
  // Collections preserve chronological order: links are sorted ASC by timestamp,
19204
19210
  // so the collection reflects the order in which items were added (oldest to newest).
19205
- this[collName] = matching.map((l) => l.target);
19211
+ let values = matching.map((l) => l.target);
19212
+ // Apply where.isInstance filtering if present
19213
+ if (collMeta.where?.isInstance && values.length > 0) {
19214
+ try {
19215
+ const className = typeof collMeta.where.isInstance === 'string'
19216
+ ? collMeta.where.isInstance
19217
+ : collMeta.where.isInstance.name;
19218
+ const filterMetadata = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").getSubjectClassMetadataFromSDNA(className);
19219
+ if (filterMetadata) {
19220
+ values = await __classPrivateFieldGet(this, _Ad4mModel_perspective, "f").batchCheckSubjectInstances(values, filterMetadata);
19221
+ }
19222
+ }
19223
+ catch (error) {
19224
+ // Keep unfiltered values on error
19225
+ }
19226
+ }
19227
+ this[collName] = values;
19206
19228
  }
19207
19229
  // Set author and timestamp
19208
19230
  if (latestAuthor) {
@@ -19212,6 +19234,8 @@ class Ad4mModel {
19212
19234
  this.timestamp = maxTimestamp;
19213
19235
  }
19214
19236
  }
19237
+ // Evaluate SurrealQL getters
19238
+ await ctor.evaluateSurrealGettersForInstance(this, __classPrivateFieldGet(this, _Ad4mModel_perspective, "f"), metadata);
19215
19239
  }
19216
19240
  catch (e) {
19217
19241
  console.error(`SurrealDB getData also failed for ${__classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f")}:`, e);
@@ -19240,6 +19264,51 @@ class Ad4mModel {
19240
19264
  `;
19241
19265
  return fullQuery;
19242
19266
  }
19267
+ /**
19268
+ * Evaluates custom SurrealQL getters for properties and collections on a specific instance.
19269
+ * @private
19270
+ */
19271
+ static async evaluateSurrealGettersForInstance(instance, perspective, metadata) {
19272
+ const safeBaseExpression = this.formatSurrealValue(instance.baseExpression);
19273
+ // Evaluate property surrealGetters
19274
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
19275
+ if (propMeta.surrealGetter) {
19276
+ try {
19277
+ // Replace 'Base' placeholder with actual base expression
19278
+ const query = propMeta.surrealGetter.replace(/Base/g, safeBaseExpression);
19279
+ // Query from node table to have graph traversal context
19280
+ const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
19281
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null && result[0].value !== 'None' && result[0].value !== '') {
19282
+ instance[propName] = result[0].value;
19283
+ }
19284
+ }
19285
+ catch (error) {
19286
+ console.warn(`Failed to evaluate surrealGetter for ${propName}:`, error);
19287
+ }
19288
+ }
19289
+ }
19290
+ // Evaluate collection surrealGetters
19291
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
19292
+ if (collMeta.surrealGetter) {
19293
+ try {
19294
+ // Replace 'Base' placeholder with actual base expression
19295
+ const query = collMeta.surrealGetter.replace(/Base/g, safeBaseExpression);
19296
+ // Query from node table to have graph traversal context
19297
+ const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
19298
+ if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
19299
+ // Filter out 'None' from collection results
19300
+ const value = result[0].value;
19301
+ instance[collName] = Array.isArray(value)
19302
+ ? value.filter((v) => v && v !== '' && v !== 'None')
19303
+ : value;
19304
+ }
19305
+ }
19306
+ catch (error) {
19307
+ console.warn(`Failed to evaluate surrealGetter for ${collName}:`, error);
19308
+ }
19309
+ }
19310
+ }
19311
+ }
19243
19312
  /**
19244
19313
  * Generates a SurrealQL query from a Query object.
19245
19314
  *
@@ -19791,9 +19860,11 @@ WHERE ${whereConditions.join(' AND ')}
19791
19860
  maxTimestamp = link.timestamp;
19792
19861
  latestAuthor = link.author;
19793
19862
  }
19794
- // Find matching property
19863
+ // Find matching property (skip those with surrealGetter)
19795
19864
  let foundProperty = false;
19796
19865
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
19866
+ if (propMeta.surrealGetter)
19867
+ continue; // Handle via surrealGetter evaluation
19797
19868
  if (propMeta.predicate === predicate) {
19798
19869
  // For properties, take the first value (or we could use timestamp to get latest)
19799
19870
  // Note: Empty objects {} are truthy, so we need to check for them explicitly
@@ -19863,9 +19934,11 @@ WHERE ${whereConditions.join(' AND ')}
19863
19934
  break;
19864
19935
  }
19865
19936
  }
19866
- // If not a property, check if it's a collection
19937
+ // If not a property, check if it's a collection (skip those with surrealGetter)
19867
19938
  if (!foundProperty) {
19868
19939
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
19940
+ if (collMeta.surrealGetter)
19941
+ continue; // Handle via surrealGetter evaluation
19869
19942
  if (collMeta.predicate === predicate) {
19870
19943
  // For collections, accumulate all values with their timestamps and indices for sorting
19871
19944
  if (!instance[collName]) {
@@ -19928,8 +20001,10 @@ WHERE ${whereConditions.join(' AND ')}
19928
20001
  // Use original index as tiebreaker for stable sorting
19929
20002
  return a.originalIndex - b.originalIndex;
19930
20003
  });
19931
- // Replace collection with sorted values
19932
- instance[collName] = pairs.map(p => p.value);
20004
+ // Replace collection with sorted values, filtering out empty strings and None
20005
+ instance[collName] = pairs
20006
+ .map(p => p.value)
20007
+ .filter((v) => v && v !== '' && v !== 'None');
19933
20008
  // Clean up temporary arrays
19934
20009
  delete instance[timestampsKey];
19935
20010
  delete instance[indicesKey];
@@ -19951,6 +20026,40 @@ WHERE ${whereConditions.join(' AND ')}
19951
20026
  console.error(`Failed to process SurrealDB instance ${base}:`, error);
19952
20027
  }
19953
20028
  }
20029
+ // Evaluate SurrealQL getters for all instances
20030
+ for (const instance of instances) {
20031
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
20032
+ }
20033
+ // Filter collections by where.isInstance if specified
20034
+ // Do this for all instances that have collections with filters
20035
+ for (const instance of instances) {
20036
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
20037
+ if (collMeta.where?.isInstance && instance[collName]?.length > 0) {
20038
+ try {
20039
+ const targetClass = collMeta.where.isInstance;
20040
+ const subjects = instance[collName];
20041
+ // Get the class metadata from SDNA to pass to batchCheckSubjectInstances
20042
+ const targetClassName = typeof targetClass === 'string'
20043
+ ? targetClass
20044
+ : targetClass.prototype?.className || targetClass.name;
20045
+ const classMetadata = await perspective.getSubjectClassMetadataFromSDNA(targetClassName);
20046
+ if (!classMetadata) {
20047
+ continue;
20048
+ }
20049
+ // Check which subjects are instances of the target class
20050
+ const validSubjects = await perspective.batchCheckSubjectInstances(subjects, classMetadata);
20051
+ instance[collName] = validSubjects;
20052
+ }
20053
+ catch (error) {
20054
+ // On error, leave the collection unfiltered rather than breaking everything
20055
+ }
20056
+ }
20057
+ }
20058
+ }
20059
+ // Evaluate SurrealQL getters for all instances
20060
+ for (const instance of instances) {
20061
+ await this.evaluateSurrealGettersForInstance(instance, perspective, metadata);
20062
+ }
19954
20063
  // Filter by where conditions that couldn't be filtered in SQL
19955
20064
  // This includes:
19956
20065
  // - author/timestamp (computed from grouped links)
@@ -103,6 +103,8 @@ export interface PropertyMetadata {
103
103
  getter?: string;
104
104
  /** Custom Prolog setter code */
105
105
  setter?: string;
106
+ /** Custom SurrealQL getter code */
107
+ surrealGetter?: string;
106
108
  /** Whether stored locally only */
107
109
  local?: boolean;
108
110
  /** Transform function */
@@ -123,6 +125,8 @@ export interface CollectionMetadata {
123
125
  isInstance?: any;
124
126
  condition?: string;
125
127
  };
128
+ /** Custom SurrealQL getter code */
129
+ surrealGetter?: string;
126
130
  /** Whether stored locally only */
127
131
  local?: boolean;
128
132
  }
@@ -335,6 +339,11 @@ export declare class Ad4mModel {
335
339
  static assignValuesToInstance(perspective: PerspectiveProxy, instance: Ad4mModel, values: ValueTuple[]): Promise<void>;
336
340
  private getData;
337
341
  static queryToProlog(perspective: PerspectiveProxy, query: Query, modelClassName?: string | null): Promise<string>;
342
+ /**
343
+ * Evaluates custom SurrealQL getters for properties and collections on a specific instance.
344
+ * @private
345
+ */
346
+ private static evaluateSurrealGettersForInstance;
338
347
  /**
339
348
  * Generates a SurrealQL query from a Query object.
340
349
  *
@@ -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
@@ -605,8 +607,10 @@ export class Ad4mModel {
605
607
  if (links && links.length > 0) {
606
608
  let maxTimestamp = null;
607
609
  let latestAuthor = null;
608
- // Process properties
610
+ // Process properties (skip those with surrealGetter)
609
611
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
612
+ if (propMeta.surrealGetter)
613
+ continue; // Handle via surrealGetter evaluation
610
614
  const matching = links.filter((l) => l.predicate === propMeta.predicate);
611
615
  if (matching.length > 0) {
612
616
  // "Latest wins" semantics: select the last element since links are ordered ASC.
@@ -652,12 +656,30 @@ export class Ad4mModel {
652
656
  this[propName] = value;
653
657
  }
654
658
  }
655
- // Process collections
659
+ // Process collections (skip those with surrealGetter)
656
660
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
661
+ if (collMeta.surrealGetter)
662
+ continue; // Handle via surrealGetter evaluation
657
663
  const matching = links.filter((l) => l.predicate === collMeta.predicate);
658
664
  // Collections preserve chronological order: links are sorted ASC by timestamp,
659
665
  // so the collection reflects the order in which items were added (oldest to newest).
660
- this[collName] = matching.map((l) => l.target);
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;
661
683
  }
662
684
  // Set author and timestamp
663
685
  if (latestAuthor) {
@@ -667,6 +689,8 @@ export class Ad4mModel {
667
689
  this.timestamp = maxTimestamp;
668
690
  }
669
691
  }
692
+ // Evaluate SurrealQL getters
693
+ await ctor.evaluateSurrealGettersForInstance(this, __classPrivateFieldGet(this, _Ad4mModel_perspective, "f"), metadata);
670
694
  }
671
695
  catch (e) {
672
696
  console.error(`SurrealDB getData also failed for ${__classPrivateFieldGet(this, _Ad4mModel_baseExpression, "f")}:`, e);
@@ -695,6 +719,51 @@ export class Ad4mModel {
695
719
  `;
696
720
  return fullQuery;
697
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
+ }
698
767
  /**
699
768
  * Generates a SurrealQL query from a Query object.
700
769
  *
@@ -1246,9 +1315,11 @@ WHERE ${whereConditions.join(' AND ')}
1246
1315
  maxTimestamp = link.timestamp;
1247
1316
  latestAuthor = link.author;
1248
1317
  }
1249
- // Find matching property
1318
+ // Find matching property (skip those with surrealGetter)
1250
1319
  let foundProperty = false;
1251
1320
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1321
+ if (propMeta.surrealGetter)
1322
+ continue; // Handle via surrealGetter evaluation
1252
1323
  if (propMeta.predicate === predicate) {
1253
1324
  // For properties, take the first value (or we could use timestamp to get latest)
1254
1325
  // Note: Empty objects {} are truthy, so we need to check for them explicitly
@@ -1318,9 +1389,11 @@ WHERE ${whereConditions.join(' AND ')}
1318
1389
  break;
1319
1390
  }
1320
1391
  }
1321
- // 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)
1322
1393
  if (!foundProperty) {
1323
1394
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1395
+ if (collMeta.surrealGetter)
1396
+ continue; // Handle via surrealGetter evaluation
1324
1397
  if (collMeta.predicate === predicate) {
1325
1398
  // For collections, accumulate all values with their timestamps and indices for sorting
1326
1399
  if (!instance[collName]) {
@@ -1383,8 +1456,10 @@ WHERE ${whereConditions.join(' AND ')}
1383
1456
  // Use original index as tiebreaker for stable sorting
1384
1457
  return a.originalIndex - b.originalIndex;
1385
1458
  });
1386
- // Replace collection with sorted values
1387
- 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');
1388
1463
  // Clean up temporary arrays
1389
1464
  delete instance[timestampsKey];
1390
1465
  delete instance[indicesKey];
@@ -1406,6 +1481,40 @@ WHERE ${whereConditions.join(' AND ')}
1406
1481
  console.error(`Failed to process SurrealDB instance ${base}:`, error);
1407
1482
  }
1408
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
+ }
1409
1518
  // Filter by where conditions that couldn't be filtered in SQL
1410
1519
  // This includes:
1411
1520
  // - 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.3",
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",
@@ -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
 
@@ -772,8 +778,9 @@ export class Ad4mModel {
772
778
  let maxTimestamp = null;
773
779
  let latestAuthor = null;
774
780
 
775
- // Process properties
781
+ // Process properties (skip those with surrealGetter)
776
782
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
783
+ if (propMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
777
784
  const matching = links.filter((l: any) => l.predicate === propMeta.predicate);
778
785
  if (matching.length > 0) {
779
786
  // "Latest wins" semantics: select the last element since links are ordered ASC.
@@ -820,12 +827,31 @@ export class Ad4mModel {
820
827
  }
821
828
  }
822
829
 
823
- // Process collections
830
+ // Process collections (skip those with surrealGetter)
824
831
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
832
+ if (collMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
825
833
  const matching = links.filter((l: any) => l.predicate === collMeta.predicate);
826
834
  // Collections preserve chronological order: links are sorted ASC by timestamp,
827
835
  // 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);
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;
829
855
  }
830
856
 
831
857
  // Set author and timestamp
@@ -836,6 +862,9 @@ export class Ad4mModel {
836
862
  (this as any).timestamp = maxTimestamp;
837
863
  }
838
864
  }
865
+
866
+ // Evaluate SurrealQL getters
867
+ await ctor.evaluateSurrealGettersForInstance(this, this.#perspective, metadata);
839
868
  } catch (e) {
840
869
  console.error(`SurrealDB getData also failed for ${this.#baseExpression}:`, e);
841
870
  }
@@ -870,6 +899,60 @@ export class Ad4mModel {
870
899
  return fullQuery;
871
900
  }
872
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
+
873
956
  /**
874
957
  * Generates a SurrealQL query from a Query object.
875
958
  *
@@ -1470,9 +1553,10 @@ WHERE ${whereConditions.join(' AND ')}
1470
1553
  latestAuthor = link.author;
1471
1554
  }
1472
1555
 
1473
- // Find matching property
1556
+ // Find matching property (skip those with surrealGetter)
1474
1557
  let foundProperty = false;
1475
1558
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1559
+ if (propMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
1476
1560
  if (propMeta.predicate === predicate) {
1477
1561
  // For properties, take the first value (or we could use timestamp to get latest)
1478
1562
  // Note: Empty objects {} are truthy, so we need to check for them explicitly
@@ -1539,9 +1623,10 @@ WHERE ${whereConditions.join(' AND ')}
1539
1623
  }
1540
1624
  }
1541
1625
 
1542
- // 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)
1543
1627
  if (!foundProperty) {
1544
1628
  for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1629
+ if (collMeta.surrealGetter) continue; // Handle via surrealGetter evaluation
1545
1630
  if (collMeta.predicate === predicate) {
1546
1631
  // For collections, accumulate all values with their timestamps and indices for sorting
1547
1632
  if (!instance[collName]) {
@@ -1603,8 +1688,10 @@ WHERE ${whereConditions.join(' AND ')}
1603
1688
  // Use original index as tiebreaker for stable sorting
1604
1689
  return a.originalIndex - b.originalIndex;
1605
1690
  });
1606
- // Replace collection with sorted values
1607
- 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');
1608
1695
  // Clean up temporary arrays
1609
1696
  delete instance[timestampsKey];
1610
1697
  delete instance[indicesKey];
@@ -1628,6 +1715,46 @@ WHERE ${whereConditions.join(' AND ')}
1628
1715
  }
1629
1716
  }
1630
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
+
1631
1758
  // Filter by where conditions that couldn't be filtered in SQL
1632
1759
  // This includes:
1633
1760
  // - 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[],