external types: add @ExternalType annotation #139

Author: Shubham

generator/lib/src/code_builder.dart

@@ -213,6 +213,8 @@ class CodeBuilder extends Builder {
     propInModel.dartFieldType = prop.dartFieldType;
     propInModel.relationTarget = prop.relationTarget;
     propInModel.hnswParams = prop.hnswParams;
+    propInModel.externalPropertyType = prop.externalPropertyType;
+    propInModel.externalPropertyName = prop.externalPropertyName;
 
     if (!prop.hasIndexFlag()) {
       propInModel.removeIndex();

generator/lib/src/code_chunks.dart

@@ -154,6 +154,14 @@ class CodeChunks {
       additionalArgs +=
           ", hnswParams: ${property.hnswParams!.toCodeString(obxInt)}";
     }
+    if (property.externalPropertyType != null) {
+      additionalArgs +=
+          ", externalPropertyType: ${property.externalPropertyType!}";
+    }
+    if (property.externalPropertyName != null) {
+      additionalArgs +=
+          ", externalPropertyName: '${property.externalPropertyName!}'";
+    }
     return '''
     $obxInt.ModelProperty(
       id: ${createIdUid(property.id)},

generator/lib/src/entity_resolver.dart

@@ -28,6 +28,7 @@ class EntityResolver extends Builder {
   final _indexChecker = const TypeChecker.fromRuntime(Index);
   final _backlinkChecker = const TypeChecker.fromRuntime(Backlink);
   final _hnswChecker = const TypeChecker.fromRuntime(HnswIndex);
+  final _externalTypeChecker = const TypeChecker.fromRuntime(ExternalProperty);
 
   @override
   FutureOr<void> build(BuildStep buildStep) async {
@@ -226,6 +227,10 @@ class EntityResolver extends Builder {
           _readHnswIndexParams(annotation, prop);
         });
 
+        _externalTypeChecker.runIfMatches(annotated, (annotation) {
+          _readExternalTypeParams(annotation, prop);
+        });
+
         // for code generation
         prop.dartFieldType =
             f.type.element!.name! + (isNullable(f.type) ? '?' : '');
@@ -555,6 +560,19 @@ class EntityResolver extends Builder {
             annotation.getField('vectorCacheHintSizeKB')!.toIntValue());
     property.hnswParams = ModelHnswParams.fromAnnotation(hnswRestored);
   }
+
+  void _readExternalTypeParams(DartObject annotation, ModelProperty property) {
+    final typeIndex =
+        _enumValueIndex(annotation.getField('type')!, "ExternalProperty.type");
+    final type = typeIndex != null ? ExternalType.values[typeIndex] : null;
+    if (type == null) {
+      throw InvalidGenerationSourceError(
+          "'type' attribute not specified in @ExternalProperty annotation");
+    }
+    final name = annotation.getField('name')!.toStringValue();
+    property.externalPropertyType = externalTypeToOBXExternalType(type);
+    property.externalPropertyName = name;
+  }
 }
 
 extension _TypeCheckerExtensions on TypeChecker {

generator/test/code_builder_test.dart

@@ -378,6 +378,38 @@ void main() {
       expect(idProperty.flags & OBXPropertyFlags.ID_SELF_ASSIGNABLE != 0, true);
     });
   });
+
+  test('ExternalType annotation', () async {
+    final source = r'''
+      library example;     
+      import 'package:objectbox/objectbox.dart';
+      
+      @Entity()
+      class Example {
+        @Id()
+        int id = 0;
+        
+        @Property(type: PropertyType.byteVector)
+        @ExternalProperty(type: ExternalType.bson, name: 'my-mongo-bson')
+        List<int>? mongoBson;
+        
+        @ExternalProperty(type: ExternalType.javaScript, name: 'my-mongo-js')
+        String? mongoJS;
+      }
+      ''';
+
+    final testEnv = GeneratorTestEnv();
+    await testEnv.run(source);
+
+    final property1 = testEnv.model.entities[0].properties
+        .firstWhere((element) => element.name == "mongoBson");
+    expect(property1.externalPropertyType, OBXExternalPropertyType.Bson);
+    expect(property1.externalPropertyName, "my-mongo-bson");
+    final property2 = testEnv.model.entities[0].properties
+        .firstWhere((element) => element.name == "mongoJS");
+    expect(property2.externalPropertyType, OBXExternalPropertyType.JavaScript);
+    expect(property2.externalPropertyName, "my-mongo-js");
+  });
 }
 
 Future<PackageConfig> _unsupported() {

objectbox/lib/src/annotations.dart

@@ -487,3 +487,109 @@ class HnswIndex {
       this.reparationBacklinkProbability,
       this.vectorCacheHintSizeKB});
 }
+
+/// A property type of an external system (e.g. another database) that has no
+/// default mapping to an ObjectBox type.
+///
+/// Use with [ExternalProperty].
+enum ExternalType {
+  /// Representing type: ByteVector
+  ///
+  /// Encoding: 1:1 binary representation, little endian (16 bytes)
+  int128,
+
+  /// Representing type: ByteVector
+  ///
+  /// Encoding: 1:1 binary representation (16 bytes)
+  uuid,
+
+  /// IEEE 754 decimal128 type, e.g. supported by MongoDB.
+  ///
+  /// Representing type: ByteVector
+  ///
+  /// Encoding: 1:1 binary representation (16 bytes)
+  decimal128,
+
+  /// A key/value map; e.g. corresponds to a JSON object or a MongoDB document
+  /// (although not keeping the key order).
+  ///
+  /// Unlike the Flex type, this must contain a map value (e.g. not a vector or
+  /// a scalar).
+  ///
+  /// Representing type: Flex
+  ///
+  /// Encoding: Flex
+  flexMap,
+
+  /// A vector (aka list or array) of flexible elements; e.g. corresponds to a
+  /// JSON array or a MongoDB array.
+  ///
+  /// Unlike the Flex type, this must contain a vector value (e.g. not a map or
+  /// a scalar).
+  ///
+  /// Representing type: Flex
+  ///
+  /// Encoding: Flex
+  flexVector,
+
+  /// Placeholder (not yet used) for a JSON document.
+  ///
+  /// Representing type: String
+  json,
+
+  /// Placeholder (not yet used) for a BSON document.
+  ///
+  /// Representing type: ByteVector
+  bson,
+
+  /// JavaScript source code.
+  ///
+  /// Representing type: String
+  javaScript,
+
+  /// A vector (array) of Int128 values.
+  int128Vector,
+
+  /// A vector (array) of Int128 values
+  uuidVector,
+
+  /// The 12-byte ObjectId type in MongoDB.
+  ///
+  /// Representing type: ByteVector
+  ///
+  /// Encoding: 1:1 binary representation (12 bytes)
+  mongoId,
+
+  /// A vector (array) of MongoId values.
+  mongoIdVector,
+
+  /// Representing type: Long
+  ///
+  /// Encoding: Two unsigned 32-bit integers merged into a 64-bit integer.
+  mongoTimestamp,
+
+  /// Representing type: ByteVector
+  ///
+  /// Encoding: 3 zero bytes (reserved, functions as padding), fourth byte is
+  /// the sub-type, followed by the binary data.
+  mongoBinary,
+
+  /// Representing type: string vector with 2 elements (index 0: pattern,
+  /// index 1: options)
+  ///
+  /// Encoding: 1:1 string representation
+  mongoRegex
+}
+
+/// Annotates a property to be stored in an external system.
+class ExternalProperty {
+  /// The name assigned to the property in the external system.
+  final String? name;
+
+  /// The type of the property in the external system.
+  /// See [ExternalType] for possible values.
+  final ExternalType type;
+
+  /// Create an ExternalProperty annotation.
+  const ExternalProperty({required this.type, this.name});
+}

objectbox/lib/src/modelinfo/enums.dart

@@ -239,3 +239,112 @@ abstract class OBXPropertyType {
   /// < Variable sized vector of Date values (high precision 64-bit timestamp).
   static const int DateNanoVector = 32;
 }
+
+int externalTypeToOBXExternalType(ExternalType type) {
+  switch (type) {
+    case ExternalType.int128:
+      return OBXExternalPropertyType.Int128;
+    case ExternalType.uuid:
+      return OBXExternalPropertyType.Uuid;
+    case ExternalType.decimal128:
+      return OBXExternalPropertyType.Decimal128;
+    case ExternalType.flexMap:
+      return OBXExternalPropertyType.FlexMap;
+    case ExternalType.flexVector:
+      return OBXExternalPropertyType.FlexVector;
+    case ExternalType.json:
+      return OBXExternalPropertyType.Json;
+    case ExternalType.bson:
+      return OBXExternalPropertyType.Bson;
+    case ExternalType.javaScript:
+      return OBXExternalPropertyType.JavaScript;
+    case ExternalType.int128Vector:
+      return OBXExternalPropertyType.Int128Vector;
+    case ExternalType.uuidVector:
+      return OBXExternalPropertyType.UuidVector;
+    case ExternalType.mongoId:
+      return OBXExternalPropertyType.MongoId;
+    case ExternalType.mongoIdVector:
+      return OBXExternalPropertyType.MongoIdVector;
+    case ExternalType.mongoTimestamp:
+      return OBXExternalPropertyType.MongoTimestamp;
+    case ExternalType.mongoBinary:
+      return OBXExternalPropertyType.MongoBinary;
+    case ExternalType.mongoRegex:
+      return OBXExternalPropertyType.MongoRegex;
+    default:
+      throw ArgumentError.value(type, 'type', 'Invalid ExternalType');
+  }
+}
+
+/// A property type of an external system (e.g. another database) that has no default mapping to an ObjectBox type.
+/// External property types numeric values start at 100 to avoid overlaps with ObjectBox's PropertyType.
+/// (And if we ever support one of these as a primary type, we could share the numeric value?)
+abstract class OBXExternalPropertyType {
+  /// Not a real type: represents uninitialized state and can be used for forward compatibility.
+  static const int Unknown = 0;
+
+  /// Representing type: ByteVector
+  /// Encoding: 1:1 binary representation, little endian (16 bytes)
+  static const int Int128 = 100;
+
+  /// Representing type: ByteVector
+  /// Encoding: 1:1 binary representation (16 bytes)
+  static const int Uuid = 102;
+
+  /// IEEE 754 decimal128 type, e.g. supported by MongoDB
+  /// Representing type: ByteVector
+  /// Encoding: 1:1 binary representation (16 bytes)
+  static const int Decimal128 = 103;
+
+  /// A key/value map; e.g. corresponds to a JSON object or a MongoDB document (although not keeping the key order).
+  /// Unlike the Flex type, this must contain a map value (e.g. not a vector or a scalar).
+  /// Representing type: Flex
+  /// Encoding: Flex
+  static const int FlexMap = 107;
+
+  /// A vector (aka list or array) of flexible elements; e.g. corresponds to a JSON array or a MongoDB array.
+  /// Unlike the Flex type, this must contain a vector value (e.g. not a map or a scalar).
+  /// Representing type: Flex
+  /// Encoding: Flex
+  static const int FlexVector = 108;
+
+  /// Placeholder (not yet used) for a JSON document.
+  /// Representing type: String
+  static const int Json = 109;
+
+  /// Placeholder (not yet used) for a BSON document.
+  /// Representing type: ByteVector
+  static const int Bson = 110;
+
+  /// JavaScript source code
+  /// Representing type: String
+  static const int JavaScript = 111;
+
+  /// A vector (array) of Int128 values
+  static const int Int128Vector = 116;
+
+  /// A vector (array) of Int128 values
+  static const int UuidVector = 118;
+
+  /// The 12-byte ObjectId type in MongoDB
+  /// Representing type: ByteVector
+  /// Encoding: 1:1 binary representation (12 bytes)
+  static const int MongoId = 123;
+
+  /// A vector (array) of MongoId values
+  static const int MongoIdVector = 124;
+
+  /// Representing type: Long
+  /// Encoding: Two unsigned 32-bit integers merged into a 64-bit integer.
+  static const int MongoTimestamp = 125;
+
+  /// Representing type: ByteVector
+  /// Encoding: 3 zero bytes (reserved, functions as padding), fourth byte is the sub-type,
+  /// followed by the binary data.
+  static const int MongoBinary = 126;
+
+  /// Representing type: string vector with 2 elements (index 0: pattern, index 1: options)
+  /// Encoding: 1:1 string representation
+  static const int MongoRegex = 127;
+}

objectbox/lib/src/modelinfo/modelproperty.dart

@@ -16,6 +16,8 @@ class ModelProperty {
   ModelEntity? entity;
   String? relationTarget;
   ModelHnswParams? hnswParams;
+  int? externalPropertyType;
+  String? externalPropertyName;
 
   /// Type used in the source dart code - used by the code generator.
   /// Starts with [_fieldReadOnlyPrefix] if the field (currently IDs only) is
@@ -114,7 +116,9 @@ class ModelProperty {
       required int flags,
       IdUid? indexId,
       this.relationTarget,
-      this.hnswParams})
+      this.hnswParams,
+      this.externalPropertyName,
+      this.externalPropertyType})
       : _name = name,
         _type = type,
         _flags = flags,
@@ -127,7 +131,9 @@ class ModelProperty {
         _dartFieldType = data['dartFieldType'] as String?,
         uidRequest = data['uidRequest'] as bool? ?? false,
         hnswParams = ModelHnswParams.fromMap(
-            data['hnswParams'] as Map<String, dynamic>?) {
+            data['hnswParams'] as Map<String, dynamic>?),
+        externalPropertyType = data['externalType'] as int?,
+        externalPropertyName = data['externalName'] as String? {
     name = data['name'] as String?;
     type = data['type'] as int?;
     flags = data['flags'] as int? ?? 0;
@@ -151,6 +157,12 @@ class ModelProperty {
       if (hnswParams != null) {
         ret['hnswParams'] = hnswParams!.toMap();
       }
+      if (externalPropertyType != null) {
+        ret['externalType'] = externalPropertyType;
+      }
+      if (externalPropertyName != null) {
+        ret['externalName'] = externalPropertyName;
+      }
     }
     return ret;
   }

objectbox/lib/src/native/model.dart

@@ -115,6 +115,16 @@ class Model {
             _cModel, hnswParams.vectorCacheHintSizeKB!));
       }
     }
+
+    final externalPropertyType = prop.externalPropertyType;
+    if (externalPropertyType != null) {
+      _check(C.model_property_external_type(_cModel, externalPropertyType));
+    }
+    final externalPropertyName = prop.externalPropertyName;
+    if (externalPropertyName != null) {
+      _check(C.model_property_external_name(
+          _cModel, externalPropertyName.toNativeUtf8().cast()));
+    }
   }
 
   void addRelation(ModelRelation rel) {