firestore_converter 1.0.7

FirestoreConverter generates Firestore withConverter implementations for the annotated class.

Reduce boilerplate code

This packages provides you with a new annotation @FirestoreConverter(defaultPath: 'someDataPath') to easily generate Firestore with_converter implementations in order to reduce boilerplate code for data models.

It is best used in conjunction with other annotations like freezed or json_serializable, but it is not a requirement.

Before:

part 'example.freezed.dart';
part 'example.g.dart';

@freezed
class Example<T> with _$Example<T> {
  factory Example(int a) = _Example;
  factory Example.fromJson(Map<String, Object?> json) => _$ExampleFromJson(json);
}

CollectionReference<Example> exampleCollection(
    [String path = 'examples']) {
  return FirebaseFirestore.instance
      .collection(path)
      .withConverter<Example>(
      fromFirestore: (snapshot, _) =>
          _$ExampleFromJson(snapshot.data()!),
      toFirestore: (instance, _) => instance.toJson());
}

DocumentReference<Example> exampleDoc(
    {String path = 'examples', required String docId}) {
  return FirebaseFirestore.instance
      .doc('$path/$docId')
      .withConverter<Example>(
      fromFirestore: (snapshot, _) =>
          _$ExampleFromJson(snapshot.data()!),
      toFirestore: (instance, _) => instance.toJson());
}

After:

part 'example.firestore_converter.dart';
part 'example.freezed.dart';
part 'example.g.dart';

@freezed
@FirestoreConverter(defaultPath: 'examples')
class Example<T> with _$Example<T> {
  factory Example(int a) = _Example;
  factory Example.fromJson(Map<String, Object?> json) => _$ExampleFromJson(json);
}

Installation

You will need to install build_runner in order to run the code generation. Install firestore_converter as dev dependency. The firestore_converter_annotation needs to be added as regular dependency:

flutter pub add dev:build_runner
flutter pub add dev:firestore_converter
flutter pub add firestore_converter_annotation

Usage

Annotate a data class with @FirestoreConverter(defaultPath: 'someDataPathInFirestore') to generate two helper functions:

• ${modelClassName}Collection
• ${modelClassName}Doc

Please note that this will be functions, not members since there is currently no way to add static functions via code generation to the model class. The initial letter of the model name will be converted to lowercase, to conform with the dart function naming conventions.

Implement fromJson and toJson

Since firestore_converter relies on instance.fromJson and instance.toJson to be present in the annotated model class, you should probably also add either freezed, json_serializable or some other annotation that will provide you with a convenient implementation of those two functions.

You can also implement them manually, although that would probably defeat the reason of using code generation in the first place.

Things to note

• JSON conversion with fromJson and toJson must be enabled / implemented.

• Uses the given path as default argument for collection and doc.

• Does not support default settings from build.yaml since path settings are individual per model class.

Example using firestore_converter with freezed

Define your model class, e.g. example.dart:

part 'example.firestore_converter.dart';
part 'example.freezed.dart';
part 'example.g.dart';

@freezed
@FirestoreConverter(defaultPath: 'examples')
class Example<T> with _$Example<T> {
  factory Example(int a) = _Example;
  factory Example.fromJson(Map<String, Object?> json) => _$ExampleFromJson(json);
}

Run the code generation to generate example.firestore_converter.dart:

flutter pub run build_runner build --delete-conflicting-outputs 

Start using it:

// Now you can easily create fully typed CollectionReferences,  DocumentReferences,
// or SnapShot objects from Firebase:
CollectionReference<Example> col1 = exampleCollection().orderBy('date', descending: true); // defaults to annotated path 'examples'
CollectionReference<Example> col2 = exampleCollection('some_other_path').orderBy('a', descending: true);
DocumentReference<Example> doc = exampleDoc(docId: 'exampleId'); // defaults to annotated path 'examples'
DocumentReference<Example> doc = exampleDoc(path: 'some_other_path', docId: 'exampleId');

// retrieve some document data
var myDoc = exampleDoc(path: 'some_other_path', docId: 'exampleId').get();
// Access typed members directly from the snapshot
debugPrint(myDoc.data().a);

References

Read the Firebase documentation about withConverter here:

https://pub.dev/documentation/cloud_firestore/latest/cloud_firestore/DocumentReference/withConverter.html

https://pub.dev/documentation/cloud_firestore/latest/cloud_firestore/CollectionReference/withConverter.html