feat(cloud_firestore_odm): Support injecting snapshot values

Author: Jjagg

packages/cloud_firestore_odm/cloud_firestore_odm/lib/annotation.dart

@@ -112,3 +112,42 @@ class Collection<T> {
 
   final String? name;
 }
+
+/// Inject a value from Firestore in the annotated field or property.
+///
+/// Add this annotation to mutable fields or setters of types that
+/// are part of a [Collection].
+///
+/// See [FirestoreValue] for the types of values that can be injected.
+///
+/// ```dart
+/// @Inject(FirestoreField.id)
+/// String? _id;
+/// String? get id => _id;
+/// ```
+class Inject {
+  const Inject(this.type);
+
+  final FirestoreValue type;
+}
+
+/// Types of values that can be injected using [Inject].
+enum FirestoreValue {
+  /// Injects the document's id.
+  ///
+  /// Expects a field of type String or String?.
+  id,
+
+  /// Injects the path to the document.
+  ///
+  /// Expects a field of type String or String?.
+  path,
+
+  /// Injects the id of the parent document if the document is in a
+  /// subcollection.
+  ///
+  /// Expects a field of type String or String?.
+  /// Use the nullable version if you also use the containing type
+  /// in root collections, otherwise the injection will throw.
+  parentId,
+}

packages/cloud_firestore_odm/cloud_firestore_odm_generator/lib/src/collection_generator.dart

@@ -1,5 +1,6 @@
 import 'package:analyzer/dart/constant/value.dart';
 import 'package:analyzer/dart/element/element.dart';
+import 'package:analyzer/dart/element/nullability_suffix.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:build/build.dart';
 import 'package:cloud_firestore_odm/annotation.dart';
@@ -26,6 +27,7 @@ class CollectionData {
     required this.queryableFields,
     required this.fromJson,
     required this.toJson,
+    required this.injections,
   }) : collectionName =
             collectionName ?? ReCase(path.split('/').last).camelCase;
 
@@ -62,12 +64,26 @@ class CollectionData {
   String Function(String json) fromJson;
   String Function(String value) toJson;
 
+  final List<FieldInjection> injections;
+
   @override
   String toString() {
     return 'CollectionData(type: $type, collectionName: $collectionName, path: $path)';
   }
 }
 
+class FieldInjection {
+  const FieldInjection({
+    required this.type,
+    required this.name,
+    required this.nullable,
+  });
+
+  final FirestoreValue type;
+  final String name;
+  final bool nullable;
+}
+
 class Data {
   Data(this.roots, this.subCollections);
 
@@ -274,6 +290,60 @@ class CollectionGenerator extends ParserGenerator<void, Data, Collection> {
       }
     }
 
+    const injectTs = TypeChecker.fromRuntime(Inject);
+    final injections = <FieldInjection>[];
+
+    final setters = collectionTargetElement.accessors;
+    final fields = collectionTargetElement.fields;
+    for (final f in [...setters, ...fields]) {
+      final annotations = injectTs.annotationsOf(f);
+
+      if (annotations.isEmpty) continue;
+      if (annotations.length > 1) {
+        throw InvalidGenerationSourceError(
+          'Only one @Inject annotation may be used for each field.',
+          element: f,
+        );
+      }
+
+      if ((f is PropertyAccessorElement && !f.isSetter) ||
+          (f is FieldElement && f.isFinal)) {
+        throw InvalidGenerationSourceError(
+          '@Inject fields or properties must be settable.',
+          element: f,
+        );
+      }
+
+      final annotation = annotations.first;
+      final annotationType = _parseInjectAnnotationType(annotation);
+
+      DartType? type;
+      if (f is PropertyAccessorElement) {
+        type = f.parameters[0].type;
+      } else if (f is FieldElement) {
+        type = f.type;
+      }
+
+      if (type == null || !type.isDartCoreString) {
+        throw InvalidGenerationSourceError(
+          'Fields with @Inject must be of type String.',
+          element: f,
+        );
+      }
+
+      // Names of setters have '=' appended.
+      final name = f is PropertyAccessorElement
+          ? f.name.substring(0, f.name.length - 1)
+          : f.name!;
+
+      final injection = FieldInjection(
+        type: annotationType,
+        name: name,
+        nullable: type.nullabilitySuffix != NullabilitySuffix.none,
+      );
+      injections.add(injection);
+    }
+
     return CollectionData(
       type: type,
       path: path,
@@ -288,6 +358,7 @@ class CollectionGenerator extends ParserGenerator<void, Data, Collection> {
       },
       queryableFields: collectionTargetElement.fields
           .where((f) => f.isPublic)
+          .whereNot((f) => injections.any((inj) => inj.name == f.name))
           .where(
             (f) =>
                 f.type.isDartCoreString ||
@@ -299,9 +370,15 @@ class CollectionGenerator extends ParserGenerator<void, Data, Collection> {
             // TODO filter list other than LIst<string|bool|num>
           )
           .toList(),
+      injections: injections,
     );
   }
 
+  FirestoreValue _parseInjectAnnotationType(DartObject annotation) {
+    return FirestoreValue
+        .values[annotation.getField('type')!.getField('index')!.toIntValue()!];
+  }
+
   @override
   Iterable<Object> generateForAll(void globalData) sync* {
     yield '''

packages/cloud_firestore_odm/cloud_firestore_odm_generator/lib/src/templates/collection_reference.dart

@@ -1,3 +1,5 @@
+import 'package:cloud_firestore_odm/annotation.dart';
+
 import '../collection_generator.dart';
 import 'template.dart';
 
@@ -18,9 +20,11 @@ abstract class ${data.collectionReferenceInterfaceName}
     DocumentSnapshot<Map<String, Object?>> snapshot,
     SnapshotOptions? options,
   ) {
-    return ${data.fromJson('snapshot.data()!')};
+    final data = ${data.fromJson('snapshot.data()!')};
+    ${_inject(data.injections)}
+    return data;
   }
- 
+
   static Map<String, Object?> toFirestore(
     ${data.type} value,
     SetOptions? options,
@@ -179,4 +183,27 @@ factory ${data.collectionReferenceInterfaceName}([
   ) : super(reference, reference);
 ''';
   }
+
+  String _inject(List<FieldInjection> injections) {
+    final buffer = StringBuffer();
+    for (final injection in injections) {
+      switch (injection.type) {
+        case FirestoreValue.id:
+          buffer.writeln('data.${injection.name} = snapshot.id;');
+          break;
+        case FirestoreValue.path:
+          buffer.writeln(
+            'data.${injection.name} = snapshot.reference.path;',
+          );
+          break;
+        case FirestoreValue.parentId:
+          buffer.writeln(
+            "data.${injection.name} = snapshot.reference.parent.parent${injection.nullable ? '?' : '!'}.id;",
+          );
+          break;
+      }
+    }
+
+    return buffer.toString();
+  }
 }