lib/src/db/model_db_impl.dart

// Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of '../../db.dart';

/// An implementation of [ModelDB] based on model class annotations.
///
/// The two constructors will scan loaded dart libraries for classes with a
/// [Kind] annotation.
///
/// An example on how to write a model class is:
///     @Kind
///     class Person extends db.Model {
///       @StringProperty
///       String name;
///
///       @IntProperty
///       int age;
///
///       @DateTimeProperty
///       DateTime dateOfBirth;
///     }
///
/// These classes must either extend [Model] or [ExpandoModel]. Furthermore
/// they must have an empty default constructor which can be used to construct
/// model objects when doing lookups/queries from datastore.
class ModelDBImpl implements ModelDB {
  final Map<_ModelDescription, Map<String, Property>> _modelDesc2Properties =
      {};
  final Map<String, _ModelDescription> _kind2ModelDesc = {};
  final Map<_ModelDescription, mirrors.ClassMirror> _modelDesc2ClassMirror = {};
  final Map<_ModelDescription, Type> _type2ModelDesc = {};
  final Map<Type, _ModelDescription> _modelDesc2Type = {};

  /// Initializes a new [ModelDB] from all libraries.
  ///
  /// This will scan all libraries for classes with a [Kind] annotation.
  ///
  /// In case an error is encountered (e.g. two model classes with the same kind
  /// name) a [StateError] will be thrown.
  ModelDBImpl() {
    // WARNING: This is O(n) of the source code, which is very bad!
    // Would be nice to have: `currentMirrorSystem().subclassesOf(Model)`
    _initialize(mirrors.currentMirrorSystem().libraries.values);
  }

  /// Initializes a new [ModelDB] from all libraries.
  ///
  /// This will scan the given [librarySymbol] for classes with a [Kind]
  /// annotation.
  ///
  /// In case an error is encountered (e.g. two model classes with the same kind
  /// name) a [StateError] will be thrown.
  ModelDBImpl.fromLibrary(Symbol librarySymbol) {
    _initialize([mirrors.currentMirrorSystem().findLibrary(librarySymbol)]);
  }

  /// Converts a [ds.Key] to a [Key]. The key returned will have the correct
  /// id type which is either `Key<String>` or `Key<int>`.
  @override
  Key fromDatastoreKey(ds.Key datastoreKey) {
    var namespace = Partition(datastoreKey.partition.namespace);
    var key = namespace.emptyKey;
    for (var element in datastoreKey.elements) {
      var type = _type2ModelDesc[_kind2ModelDesc[element.kind]!];
      if (type == null) {
        throw StateError(
            'Could not find a model associated with kind "${element.kind}". '
            'Please ensure a model class was annotated with '
            '`@Kind(name: "${element.kind}")`.');
      }
      final elementId = element.id;
      if (elementId is String) {
        key = key.append<String>(type, id: elementId);
      } else if (elementId is int) {
        key = key.append<int>(type, id: elementId);
      } else {
        throw StateError('Key must be either String or int, but '
            'was ${elementId.runtimeType} for key ${element.kind}');
      }
    }
    return key;
  }

  /// Converts a [Key] to a [ds.Key].
  @override
  ds.Key toDatastoreKey(Key dbKey) {
    var elements = <ds.KeyElement>[];
    var currentKey = dbKey;
    while (!currentKey.isEmpty) {
      var id = currentKey.id;

      var modelDescription = _modelDescriptionForType(currentKey.type)!;
      var kind = modelDescription.kindName(this);

      var useIntegerId = modelDescription.useIntegerId;

      if (useIntegerId && id != null && id is! int) {
        throw ArgumentError('Expected an integer id property but '
            'id was of type ${id.runtimeType}');
      }
      if (!useIntegerId && (id != null && id is! String)) {
        throw ArgumentError('Expected a string id property but '
            'id was of type ${id.runtimeType}');
      }

      elements.add(ds.KeyElement(kind, id));
      currentKey = currentKey.parent!;
    }
    var partition = currentKey._parent as Partition;
    return ds.Key(elements.reversed.toList(),
        partition: ds.Partition(partition.namespace));
  }

  /// Converts a [Model] instance to a [ds.Entity].
  @override
  ds.Entity toDatastoreEntity(Model model) {
    try {
      var modelDescription = _modelDescriptionForType(model.runtimeType)!;
      return modelDescription.encodeModel(this, model);
    } catch (error, stack) {
      throw ArgumentError('Error while encoding entity ($error, $stack).');
    }
  }

  /// Converts a [ds.Entity] to a [Model] instance.
  @override
  T? fromDatastoreEntity<T extends Model>(ds.Entity? entity) {
    if (entity == null) {
      return null;
    }
    var key = fromDatastoreKey(entity.key);
    var kind = entity.key.elements.last.kind;
    var modelDescription = _kind2ModelDesc[kind];
    if (modelDescription == null) {
      throw StateError('Trying to deserialize entity of kind '
          '$kind, but no Model class available for it.');
    }

    try {
      return modelDescription.decodeEntity<T>(this, key, entity);
    } catch (error, stack) {
      throw StateError('Error while decoding entity ($error, $stack).');
    }
  }

  /// Returns the string representation of the kind of model class [type].
  ///
  /// If the model class `type` is not found it will throw an `ArgumentError`.
  @override
  String kindName(Type type) {
    var kind = _modelDesc2Type[type]?.kind;
    if (kind == null) {
      throw ArgumentError('The class $type was not associated with a kind.');
    }
    return kind;
  }

  /// Returns the name of the property corresponding to the kind [kind] and
  /// [fieldName].
  @override
  String? fieldNameToPropertyName(String kind, String fieldName) {
    var modelDescription = _kind2ModelDesc[kind];
    if (modelDescription == null) {
      throw ArgumentError('The kind "$kind" is unknown.');
    }
    return modelDescription.fieldNameToPropertyName(fieldName);
  }

  /// Converts [value] according to the [Property] named [name] in [type].
  @override
  Object? toDatastoreValue(String kind, String fieldName, Object? value,
      {bool forComparison = false}) {
    var modelDescription = _kind2ModelDesc[kind];
    if (modelDescription == null) {
      throw ArgumentError('The kind "$kind" is unknown.');
    }
    return modelDescription.encodeField(this, fieldName, value,
        forComparison: forComparison);
  }

  Iterable<_ModelDescription> get _modelDescriptions {
    return _modelDesc2Type.values;
  }

  Map<String, Property> _propertiesForModel(
      _ModelDescription modelDescription) {
    return _modelDesc2Properties[modelDescription]!;
  }

  _ModelDescription? _modelDescriptionForType(Type? type) {
    return _modelDesc2Type[type!];
  }

  mirrors.ClassMirror? _modelClass(_ModelDescription md) {
    return _modelDesc2ClassMirror[md];
  }

  void _initialize(Iterable<mirrors.LibraryMirror> libraries) {
    for (var lm in libraries) {
      lm.declarations.values
          .whereType<mirrors.ClassMirror>()
          .where((d) => d.hasReflectedType)
          .forEach(_tryLoadNewModelClass);
    }

    // Ask every [ModelDescription] to compute whatever global state it wants
    // to have.
    for (var modelDescription in _modelDescriptions) {
      modelDescription.initialize(this);
    }

    // Ask every [ModelDescription] whether we should register it with a given
    // kind name.
    for (var modelDescription in _modelDescriptions) {
      var kindName = modelDescription.kindName(this);
      if (_kind2ModelDesc.containsKey(kindName)) {
        throw StateError('Cannot have two ModelDescriptions '
            'with the same kind ($kindName)');
      }
      _kind2ModelDesc[kindName] = modelDescription;
    }
  }

  void _tryLoadNewModelClass(mirrors.ClassMirror classMirror) {
    Kind? kindAnnotation;
    for (var instance in classMirror.metadata) {
      if ((instance.reflectee as Object).runtimeType == Kind) {
        if (kindAnnotation != null) {
          throw StateError(
              'Cannot have more than one ModelMetadata() annotation '
              'on a Model class');
        }
        kindAnnotation = instance.reflectee as Kind?;
      }
    }

    if (kindAnnotation != null) {
      var name = kindAnnotation.name;
      var integerId = kindAnnotation.idType == IdType.Integer;
      var stringId = kindAnnotation.idType == IdType.String;

      // Fall back to the class name.
      name ??= mirrors.MirrorSystem.getName(classMirror.simpleName);

      // This constraint should be guaranteed by the Kind() const constructor.
      assert((integerId && !stringId) || (!integerId && stringId));

      _tryLoadNewModelClassFull(classMirror, name, integerId);
    }
  }

  static bool _isRequiredAnnotation(mirrors.InstanceMirror annotation) {
    return annotation.type.simpleName == #Required;
  }

  /// Returns true if a  constructor invocation is valid even if the specified
  /// [parameter] is omitted.
  ///
  /// This is  true for named parameters, optional parameters, and parameters
  /// with a default value.
  static bool _canBeOmitted(mirrors.ParameterMirror parameter) {
    if (parameter.metadata.any(_isRequiredAnnotation)) {
      return false;
    }
    return parameter.isOptional ||
        parameter.isNamed ||
        parameter.hasDefaultValue;
  }

  /// Returns true if the specified [classMirror] has a default (unnamed)
  /// constructor that accepts an empty arguments list.
  @visibleForTesting
  static bool hasDefaultConstructor(mirrors.ClassMirror classMirror) {
    for (var declaration in classMirror.declarations.values) {
      if (declaration is mirrors.MethodMirror) {
        if (declaration.isConstructor &&
            declaration.constructorName == const Symbol('') &&
            declaration.parameters.every(_canBeOmitted)) {
          return true;
        }
      }
    }
    return false;
  }

  void _tryLoadNewModelClassFull(
      mirrors.ClassMirror modelClass, String name, bool useIntegerId) {
    assert(!_modelDesc2Type.containsKey(modelClass.reflectedType));

    _ModelDescription modelDesc;
    if (_isExpandoClass(modelClass)) {
      modelDesc = _ExpandoModelDescription(name, useIntegerId);
    } else {
      modelDesc = _ModelDescription(name, useIntegerId);
    }

    _type2ModelDesc[modelDesc] = modelClass.reflectedType;
    _modelDesc2Type[modelClass.reflectedType] = modelDesc;
    _modelDesc2ClassMirror[modelDesc] = modelClass;
    _modelDesc2Properties[modelDesc] =
        _propertiesFromModelDescription(modelClass);

    // Ensure we have an empty constructor.
    if (!hasDefaultConstructor(modelClass)) {
      throw StateError('Class ${modelClass.simpleName} does not have a default '
          'constructor.');
    }
  }

  Map<String, Property> _propertiesFromModelDescription(
      mirrors.ClassMirror modelClassMirror) {
    var properties = <String, Property>{};
    var propertyNames = <String>{};

    // Loop over all classes in the inheritance path up to the Object class.
    while (modelClassMirror.superclass != null) {
      var memberMap = modelClassMirror.instanceMembers;
      // Loop over all declarations (which includes fields)
      modelClassMirror.declarations
          .forEach((Symbol fieldSymbol, mirrors.DeclarationMirror decl) {
        // Look if the symbol is a getter and we have metadata attached to it.
        if (memberMap.containsKey(fieldSymbol) &&
            memberMap[fieldSymbol]!.isGetter) {
          final propertyAnnotations = decl.metadata
              .map((mirrors.InstanceMirror mirror) => mirror.reflectee)
              .whereType<Property>()
              .toList();

          if (propertyAnnotations.length > 1) {
            throw StateError(
                'Cannot have more than one Property annotation on a model '
                'field.');
          } else if (propertyAnnotations.length == 1) {
            var property = propertyAnnotations.first;

            // Get a String representation of the field and the value.
            var fieldName = mirrors.MirrorSystem.getName(fieldSymbol);

            // Determine the name to use for the property in datastore.
            var propertyName = property.propertyName;
            propertyName ??= fieldName;

            if (properties.containsKey(fieldName)) {
              throw StateError(
                  'Cannot have two Property objects describing the same field '
                  'in a model object class hierarchy.');
            }

            if (propertyNames.contains(propertyName)) {
              throw StateError(
                  'Cannot have two Property objects mapping to the same '
                  'datastore property name "$propertyName".');
            }
            properties[fieldName] = property;
            propertyNames.add(propertyName);
          }
        }
      });
      modelClassMirror = modelClassMirror.superclass!;
    }

    return properties;
  }

  final _originalExpandoModelClass = mirrors.reflectClass(ExpandoModel);
  final _originalModelClass = mirrors.reflectClass(Model);

  bool _isExpandoClass(mirrors.ClassMirror? modelClass) {
    while (modelClass != null && modelClass.superclass != modelClass) {
      if (modelClass.originalDeclaration == _originalExpandoModelClass) {
        return true;
      } else if (modelClass.originalDeclaration == _originalModelClass) {
        return false;
      }

      modelClass = modelClass.superclass;
    }
    throw StateError('This should be unreachable.');
  }
}

class _ModelDescription<T extends Model> {
  final HashMap<String, String> _property2FieldName = HashMap<String, String>();
  final HashMap<String, String> _field2PropertyName = HashMap<String, String>();
  final Set<String> _indexedProperties = <String>{};
  final Set<String> _unIndexedProperties = <String>{};

  final String kind;
  final bool useIntegerId;

  _ModelDescription(this.kind, this.useIntegerId);

  void initialize(ModelDBImpl db) {
    // Compute propertyName -> fieldName mapping.
    db._propertiesForModel(this).forEach((String fieldName, Property prop) {
      // The default of a datastore property name is the fieldName.
      // It can be overridden with [Property.propertyName].
      var propertyName = prop.propertyName;
      propertyName ??= fieldName;

      _property2FieldName[propertyName] = fieldName;
      _field2PropertyName[fieldName] = propertyName;
    });

    // Compute properties & unindexed properties
    db._propertiesForModel(this).forEach((String fieldName, Property prop) {
      var propertyName = prop.propertyName;
      propertyName ??= fieldName;

      if (prop.indexed) {
        _indexedProperties.add(propertyName);
      } else {
        _unIndexedProperties.add(propertyName);
      }
    });
  }

  String kindName(ModelDBImpl db) => kind;

  ds.Entity encodeModel(ModelDBImpl db, T model) {
    var key = db.toDatastoreKey(model.key);

    var properties = <String, Object?>{};
    var mirror = mirrors.reflect(model);

    db._propertiesForModel(this).forEach((String fieldName, Property prop) {
      _encodeProperty(db, model, mirror, properties, fieldName, prop);
    });

    return ds.Entity(key, properties,
        unIndexedProperties: _unIndexedProperties);
  }

  void _encodeProperty(
      ModelDBImpl db,
      Model model,
      mirrors.InstanceMirror mirror,
      Map properties,
      String fieldName,
      Property prop) {
    var propertyName = prop.propertyName;
    propertyName ??= fieldName;

    var value =
        mirror.getField(mirrors.MirrorSystem.getSymbol(fieldName)).reflectee;
    if (!prop.validate(db, value)) {
      throw StateError('Property validation failed for '
          'property $fieldName while trying to serialize entity of kind '
          '${model.runtimeType}. ');
    }
    properties[propertyName] = prop.encodeValue(db, value);
  }

  H decodeEntity<H extends Model>(ModelDBImpl db, Key key, ds.Entity entity) {
    // NOTE: this assumes a default constructor for the model classes!
    var classMirror = db._modelClass(this)!;
    var mirror = classMirror.newInstance(const Symbol(''), []);

    // Set the id and the parent key
    final model = mirror.reflectee as Model;
    model.id = key.id;
    model.parentKey = key.parent;

    db._propertiesForModel(this).forEach((String fieldName, Property prop) {
      _decodeProperty(db, entity, mirror, fieldName, prop);
    });
    return mirror.reflectee as H;
  }

  void _decodeProperty(ModelDBImpl db, ds.Entity entity,
      mirrors.InstanceMirror mirror, String fieldName, Property prop) {
    var propertyName = fieldNameToPropertyName(fieldName);

    var rawValue = entity.properties[propertyName!];
    var value = prop.decodePrimitiveValue(db, rawValue);

    if (!prop.validate(db, value)) {
      throw StateError('Property validation failed while '
          'trying to deserialize entity of kind '
          '${entity.key.elements.last.kind} (property name: $propertyName)');
    }

    try {
      mirror.setField(mirrors.MirrorSystem.getSymbol(fieldName), value);
      // ignore: avoid_catching_errors
    } on TypeError catch (error) {
      throw StateError(
        'Error trying to set property "${prop.propertyName}" '
        'to $value for field "$fieldName": $error',
      );
    }
  }

  String? fieldNameToPropertyName(String fieldName) {
    return _field2PropertyName[fieldName];
  }

  String? propertyNameToFieldName(ModelDBImpl db, String propertySearchName) {
    return _property2FieldName[propertySearchName];
  }

  Object? encodeField(ModelDBImpl db, String fieldName, Object? value,
      {bool enforceFieldExists = true, bool forComparison = false}) {
    var property = db._propertiesForModel(this)[fieldName];
    if (property != null) {
      return property.encodeValue(db, value, forComparison: forComparison);
    }
    if (enforceFieldExists) {
      throw ArgumentError(
          'A field named "$fieldName" does not exist in kind "$kind".');
    }
    return null;
  }
}

// NOTE/TODO:
// Currently expanded properties are only
//   * decoded if there are no clashes in [usedNames]
//   * encoded if there are no clashes in [usedNames]
// We might want to throw an error if there are clashes, because otherwise
//   - we may end up removing properties after a read-write cycle
//   - we may end up dropping added properties in a write
// ([usedNames] := [realFieldNames] + [realPropertyNames])
class _ExpandoModelDescription extends _ModelDescription<ExpandoModel> {
  late Set<String> realFieldNames;
  late Set<String> realPropertyNames;
  late Set<String> usedNames;

  _ExpandoModelDescription(String kind, bool useIntegerId)
      : super(kind, useIntegerId);

  @override
  void initialize(ModelDBImpl db) {
    super.initialize(db);

    realFieldNames = Set<String>.from(_field2PropertyName.keys);
    realPropertyNames = Set<String>.from(_property2FieldName.keys);
    usedNames = <String>{}
      ..addAll(realFieldNames)
      ..addAll(realPropertyNames);
  }

  @override
  ds.Entity encodeModel(ModelDBImpl db, ExpandoModel model) {
    var entity = super.encodeModel(db, model);
    var properties = entity.properties;
    model.additionalProperties.forEach((String key, Object? value) {
      // NOTE: All expanded properties will be indexed.
      if (!usedNames.contains(key)) {
        properties[key] = value;
      }
    });
    return entity;
  }

  @override
  T decodeEntity<T extends Model>(ModelDBImpl db, Key key, ds.Entity entity) {
    var model = super.decodeEntity(db, key, entity) as ExpandoModel;
    var properties = entity.properties;
    properties.forEach((String key, Object? value) {
      if (!usedNames.contains(key)) {
        model.additionalProperties[key] = value;
      }
    });
    // TODO: check if there is a more elegant solution than this
    return model as T;
  }

  @override
  String fieldNameToPropertyName(String fieldName) {
    var propertyName = super.fieldNameToPropertyName(fieldName);
    // If the ModelDescription doesn't know about [fieldName], it's an
    // expanded property, where propertyName == fieldName.
    propertyName ??= fieldName;
    return propertyName;
  }

  @override
  String propertyNameToFieldName(ModelDBImpl db, String propertyName) {
    var fieldName = super.propertyNameToFieldName(db, propertyName);
    // If the ModelDescription doesn't know about [propertyName], it's an
    // expanded property, where propertyName == fieldName.
    fieldName ??= propertyName;
    return fieldName;
  }

  @override
  Object encodeField(ModelDBImpl db, String fieldName, Object? value,
      {bool enforceFieldExists = true, bool forComparison = false}) {
    // The [enforceFieldExists] argument is intentionally ignored.

    var primitiveValue = super.encodeField(db, fieldName, value,
        enforceFieldExists: false, forComparison: forComparison);
    // If superclass can't encode field, we return value here (and assume
    // it's primitive)
    // NOTE: Implicit assumption:
    // If value != null then superclass will return != null.
    // TODO: Ensure [value] is primitive in this case.
    primitiveValue ??= value;
    return primitiveValue!;
  }
}