An object-oriented data access API and ODM for Firebase's Firestore and the Realtime Database

Firestorm for Flutter is a data access and ODM (Object-Document Mapping) tool for Firebase's Firestore and Realtime Database. It is designed to enable the rapid development of cross-platform Flutter applications using these two datastores, by providing a simple object-oriented API for interacting with data with minimal to no overheads.

The primary aim of Firestorm is to reduce development effort and time by providing an easy to use API for interacting with these datastores in an object-oriented way, and with minimal to no overheads in terms of performance or flexibility.

Developed by Dr Nicos Kasenides at UCLan Cyprus.

Not convinced? Check out the code comparison.

---

Contents

• Features
• Getting started
  • Installation
• Getting started with Firestorm for Flutter
• API Guide
• Feature support
• Platform support
• Performance
• Information
  • Requirements
  • Known issues
  • Bug reports and feature requests
• License

Features

1. An easy-to-use data access API.
2. Object-oriented data access with support for custom classes and inheritance.
3. Built-in datastore type safety.
4. Automatic serialization and deserialization of data from/to objects.
5. Easy access to advanced features such as real-time updates, offline persistence, transactions, batch writes, and more.
6. Support for both Firestore and Realtime Database.

Getting started

Installation

Install/import Firestorm by running the following command in your project folder terminal:

flutter pub add firestorm

--- OR ---

By adding it to your pubspec.yaml file:

dependencies:
  firestorm: ^0.2.4

Getting started with Firestorm for Flutter

After importing Firestorm in your project, you can start using it by following these steps:

1. Configure the google-services.json file in your project.

   • For Android, place it in android/app/.
   • For iOS, place it in ios/Runner/.
   • For web, place it in web/.
   • For desktop, place it in linux/, macos/, or windows/ as appropriate.
   • For more information on how to generate this file, refer to the official Firebase documentation for Android, iOS, and Web.
   • You also need to configure each sub-project to use Firebase with the correct dependencies.

2. Create your custom data classes

   • Follow the guide on how to define your data classes.

3. Install and run build_runner to perform checks and generate firestorm_models.dart:

   • To install, run:

     flutter pub add build_runner 
     

   • To generate, run:

     dart run build_runner build --delete-conflicting-outputs
     

     This will generate a file called firestorm_models.dart in the lib/generated/ directory of your project. This file contains the generated code for your custom classes and is required for Firestorm to work with them.

4. Initialize Firestorm in your application.

   import 'package:firebase_core/firebase_core.dart';
   import 'package:firestorm/firestorm.dart';
   
   void main() async {
     WidgetsFlutterBinding.ensureInitialized(); //Ensures Flutter is initialized before Firebase
     await FS.init(); //Initialize Firestorm to use Firestore
     await RDB.init(); //Initialize Firestorm to use Realtime Database
     registerClasses(); //Registers custom classes. Imported from generated file [firestorm_models.dart].
        
     runApp(MyApp()); //Run your app normally here.
   }
   

5. Import the generated firestorm_models.dart file in your code (main.dart):
   • This file contains the generated code for your custom classes and is required for Firestorm to work with them.
   • You can import it like this:

     import '<your_project>/generated/firestorm_models.dart';
     

6. Start using Firestorm in your code
   • You can now start using Firestorm to interact with Firestore or Realtime Database.
   • For example, you can create, read, update, and delete documents in Firestore or Realtime Database using your custom classes.
   • For more information on how to use Firestorm, refer to the API Guide.

Summary

---

API Guide

For a detailed guide on how to use Firestorm, refer to the API Guide. The guide covers the following topics:

• How to create, read, update, and delete documents in Firestore and Realtime Database.
• How to use real-time updates with Firestorm.
• How to use transactions and batch writes for Firestore.
• How to use advanced features such as offline persistence, queries, and more.

Feature support

Even though Firestorm provides a unified API for both Firestore and Realtime Database, it is important to note that the two databases have different capabilities and limitations. Firestorm aims to provide a consistent interface while respecting the unique features of each database.

• Firestore: A NoSQL document database that allows for complex queries, offline support, and real-time updates.
• Realtime Database: A cloud-hosted NoSQL database that provides real-time synchronization and is optimized for low-latency data access.

Feature	Firestore	Realtime Database
Basic operations (CRUD)	✅	✅
Subcollections	✅	✅
Real-time Listeners	✅	✅
Offline Support	✅	✅
Batch Writes	✅	❌
Queries	Complex	Basic only
Transactions	✅	❌
Pagination	✅	❌

Platform support

Platform	Firestore	Realtime Database
Android	✅	✅
iOS	✅	✅
Web	✅	✅
Windows	✅	❌
macOS	✅	✅
Linux	❌	❌

Performance

A primary consideration for Firestorm is efficient and minimal overheads. It uses the official Firebase packages for Dart, which are optimized for performance. Where necessary, it utilizes various techniques such as multithreading and multiplexing to ensure that the API is efficient and does not introduce unnecessary overheads. Firestorm's API is designed to be easy to use while its operations run at high performance.

You can find the performance benchmarks and comparisons in the performance section.

Information

Requirements

• Dart 3.2 or higher

Firestorm is designed to be used with Dart and Flutter, and is built on top of the official Firebase packages for Dart:

• firebase_core
• firebase_database
• cloud_firestore

You do not need to add these packages manually, as Firestorm will automatically add them as dependencies when you install it.

Known issues

No known issues.

Bug reports and feature requests

If you find a bug or have a feature request, please report it on our GitHub repository.

View the change log for the latest updates and changes to Firestorm.

License

Firestorm is open-source and is released under the Apache 2.0 License. See the LICENSE file for more information.