firefuel 0.5.0

A Firebase Cloud Firestore library to fuel your application's growth!

0.5.0

Requires Dart 3.10 / Flutter 3.38 and firefuel_core 0.2.0. Read the migration guide: http://firefueldocs.com/#/migrating

fix!: make queries and writes do what their names say

• OrderDirection.newestToOldest / oldestToNewest sorted in reverse; OrderBy.docId ignored descending aliases
• paginate dropped the chunk's clauses and limit after the first page
• Clause(arrayContainsAny:) was never sent to Firestore
• Range filters on several fields are allowed (Firestore supports up to 10); MoreThanOneFieldInRangeClauseException is removed
• replace is a server-checked update: atomic, read-free, offline-safe, works after a createById in the same batch (#43), and fails not-found for a missing document instead of doing nothing
• countAll / countWhere take the AggregateSource? source they use, instead of an ignored GetOptions
• FirefuelBatch rolled over one op early and over-counted totalTransactionsCommitted
• update / replaceFields serialize through toFirestore like every other write
• Clause(isNull: false) no longer drops its orderBy; Clause / OrderBy equality includes the operator, byId and the effective direction; an empty last page keeps its cursor; cursors and limitToLast require an order that already satisfies Firestore (it was silently rewritten under them)
• Collections resolve Firefuel.firestore per call instead of capturing it at construction; Firefuel.firestore throws a StateError before initialize

feat!: own the Either

• Either, Left, Right, left, right come from firefuel_core instead of package:dartz (unmaintained since 2021). Same names and methods, plus leftMap, flatMap and exhaustive switch

feat!: pages are package:chunk's Chunk

• paginate(FirefuelQuery, {after}) returns Chunk<T, DocumentSnapshot<T?>> (alias FirefuelPage<T>), the type paginated_builder uses; firefuel's own Chunk is removed. firefuel re-exports Chunk, ChunkStatus, Chunker and DataChunker.
• FirefuelCollection.dataChunker(query) plugs a collection into Chunker and paginated_builder.
• The default page size is 50 (Chunk.defaultLimit), not 25. A last chunk passed back is returned unchanged.

feat: queries as values

• FirefuelQuery (clauses, orderBy, limit / limitToLast, StartCursor / EndCursor) read through query / streamQuery
• Clause.or / Clause.and (#35); Clause is sealed
• aggregate(query, count:, sums:, averages:) in one request

feat: listening with metadata

• snapshots(query, options:) → FirefuelQuerySnapshot (values, docs with id/path, changes, isFromCache, hasPendingWrites); docSnapshots(docId)
• ListenOptions (includeMetadataChanges, ListenSource); FirefuelDoc.ancestorId

feat: collection groups

• FirefuelCollectionGroup<T> with the full read surface; FirefuelQueryRepository<T> for Either results over any readable query

feat: writes

• FieldUpdate values (increment, arrayUnion, arrayRemove, delete, serverTimestamp) in updateFields, and ServerTimestamp returned from toJson, on every write path
• increment and deleteField helpers
• Firefuel.runTransaction with typed transaction.of(collection) scopes and an atomic readOrCreate
• Firefuel.batch(): atomic batches across collections
• FirefuelCollection(path, firestore:) pins a collection to an instance

feat: observing and offline

• FirefuelObserver hears every failure guard / guardStream handle (#18, in part); failures are no longer printed
• WriteAcknowledgement.local completes writes once queued locally, so offline UIs do not hang (#62); Firefuel.waitForPendingWrites

chore: upgrade dependencies

• New dependency chunk ^1.1.0; cloud_firestore ^6.3.0 → ^6.10.0, fake_cloud_firestore ^4.3.0, very_good_analysis ^11.0.0, equatable >=2.1.0 <4.0.0
• Removed dartz and universal_io
• Re-exports FirebaseFirestore, Timestamp, Source, ListenSource, ServerTimestampBehavior, DocumentChangeType, DocumentReference, Transaction, WriteBatch (#60); QueryX helpers are internal

0.4.7

feat: add readMany and streamMany for reading documents by id

• FirefuelCollection and FirefuelRepository: readMany, streamMany
• Results preserve the requested document id order
• Missing documents are returned as null entries

feat: add streamChanges for typed document-change streams

• FirefuelCollection and FirefuelRepository: streamChanges
• Removed documents are excluded by default and can be included with includeRemoved

feat: add document field update helpers

• FirefuelCollection, FirefuelRepository, and FirefuelBatch: updateFields, arrayUnion, arrayRemove, serverTimestamp
• Re-export FieldValue from package:firefuel/firefuel.dart for callers that need custom transforms

0.4.6

feat: expose Firestore sum and average aggregation queries

• FirefuelCollection and FirefuelRepository: sumAll, sumWhere, averageAll, averageWhere
• Optional AggregateSource? source on each method (forwarded to AggregateQuery.get)
• Re-export AggregateSource, sum, and average from package:firefuel/firefuel.dart

feat: add Clause.fieldMatchingRangeOrderingRule for the field that must lead orderBy with a range Clause

fix: where and streamWhere with orderBy and a range Clause were using the first Clause in the list for the leading OrderBy instead of the range field

• FirefuelCollection: fieldToMatch for orderBy with a range Clause

chore: upgrade dependencies

Output from flutter pub upgrade --major-versions --tighten

Resolving dependencies...
Downloading packages...
  async 2.13.0 (2.13.1 available)
> cel 0.5.4+1 (was 0.5.3)
< characters 1.4.0 (was 1.4.1) (1.4.1 available)
> fake_firebase_security_rules 0.5.4 (was 0.5.3)
* firefuel_core 0.1.7 (was 0.1.6)
< leak_tracker 10.0.9 (was 11.0.2) (11.0.2 available)
< leak_tracker_flutter_testing 3.0.9 (was 3.0.10) (3.0.10 available)
< leak_tracker_testing 3.0.1 (was 3.0.2) (3.0.2 available)
> logger 2.7.0 (was 2.6.1)
< matcher 0.12.17 (was 0.12.19) (0.12.19 available)
< material_color_utilities 0.11.1 (was 0.13.0) (0.13.0 available)
< meta 1.16.0 (was 1.17.0) (1.18.2 available)
> more 4.7.0 (was 4.5.0)
  rx 0.4.0 (0.5.0 available)
  source_span 1.10.1 (1.10.2 available)
< test_api 0.7.4 (was 0.7.10) (0.7.11 available)
< vector_math 2.1.4 (was 2.2.0) (2.3.0 available)
< very_good_analysis 9.0.0 (was 10.2.0) (10.2.0 available)
  vm_service 15.0.0 (15.1.0 available)
These packages are no longer being depended on:
- tuple 2.0.2

0.4.5

feat: allow optional GetOptions to methods reading data

• FirefuelCollection: countAll, countWhere, limit, orderBy, paginate, read, readAll, readOrCreate, replace, where, whereById,
• FirefuelRepository: same as above

fix: FirefuelRepository.streamWhere and FirefuelRepository.where were not passing orderBy clauses to the collection

0.4.4

chore: upgrade dependencies

Output from flutter pub upgrade --major-versions --tighten --no-example

Resolving dependencies...
Changed 9 constraints in pubspec.yaml:
  cloud_firestore: ^5.5.0 -> ^6.0.0
  fake_cloud_firestore: ^3.1.0 -> ^4.0.0
  very_good_analysis: ^6.0.0 -> ^9.0.0
  dartz: ^0.10.0 -> ^0.10.1
  equatable: ^2.0.5 -> ^2.0.7
  firefuel_core: ^0.1.0 -> ^0.1.6
  stack_trace: ^1.10.0 -> ^1.12.1
  universal_io: ^2.0.4 -> ^2.2.2
  mocktail: ^1.0.3 -> ^1.0.4
Resolving dependencies...
Downloading packages...
  characters 1.4.0 (1.4.1 available)
  leak_tracker 10.0.9 (11.0.1 available)
  leak_tracker_flutter_testing 3.0.9 (3.0.10 available)
  leak_tracker_testing 3.0.1 (3.0.2 available)
  material_color_utilities 0.11.1 (0.13.0 available)
  meta 1.16.0 (1.17.0 available)
  more 4.5.0 (4.6.0 available)
  rx 0.4.0 (0.5.0 available)
  test_api 0.7.4 (0.7.7 available)
  vector_math 2.1.4 (2.2.0 available)
  vm_service 15.0.0 (15.0.2 available)

0.4.3

chore: upgrade dependencies

Output from flutter pub upgrade --major-versions --no-example

Resolving dependencies...
Changed 3 constraints in pubspec.yaml:
  cloud_firestore: ^4.15.5 -> ^5.5.0
  fake_cloud_firestore: ^2.1.0 -> ^3.1.0
  very_good_analysis: ^5.1.0 -> ^6.0.0
Resolving dependencies...
Downloading packages...
> _flutterfire_internals 1.3.46 (was 1.3.30)
> antlr4 4.13.2 (was 4.13.1)
  async 2.11.0 (2.12.0 available)
  boolean_selector 2.1.1 (2.1.2 available)
  characters 1.3.0 (1.3.1 available)
  clock 1.1.1 (1.1.2 available)
> cloud_firestore 5.5.0 (was 4.17.0)
> cloud_firestore_platform_interface 6.5.0 (was 6.2.0)
> cloud_firestore_web 4.3.4 (was 3.12.0)
  collection 1.18.0 (1.19.1 available)
> equatable 2.0.7 (was 2.0.5)
  fake_async 1.3.1 (1.3.2 available)
> fake_cloud_firestore 3.1.0 (was 2.4.9)
> firebase_core 3.8.0 (was 2.30.0)
> firebase_core_platform_interface 5.3.0 (was 5.0.0)
> firebase_core_web 2.18.1 (was 2.15.0)
> firefuel_core 0.1.4 (was 0.1.3)
> leak_tracker 10.0.5 (was 10.0.0) (10.0.8 available)
> leak_tracker_flutter_testing 3.0.5 (was 2.0.1) (3.0.9 available)
> leak_tracker_testing 3.0.1 (was 2.0.1)
> logger 2.5.0 (was 2.2.0)
> logging 1.3.0 (was 1.2.0)
  matcher 0.12.16+1 (0.12.17 available)
> material_color_utilities 0.11.1 (was 0.8.0) (0.12.0 available)
> meta 1.15.0 (was 1.11.0) (1.16.0 available)
> mocktail 1.0.4 (was 1.0.3)
> more 4.4.0 (was 4.2.0)
  path 1.9.0 (1.9.1 available)
> quiver 3.2.2 (was 3.2.1)
> rx 0.4.0 (was 0.3.0)
> rxdart 0.28.0 (was 0.27.7)
  stack_trace 1.11.1 (1.12.0 available)
  string_scanner 1.2.0 (1.4.0 available)
> test_api 0.7.2 (was 0.6.1) (0.7.4 available)
> typed_data 1.4.0 (was 1.3.2)
> very_good_analysis 6.0.0 (was 5.1.0)
> vm_service 14.2.5 (was 13.0.0) (14.3.1 available)
> web 1.1.0 (was 0.5.1)

0.4.2

chore: upgrade dependencies

Output from flutter pub upgrade --major-versions

> _flutterfire_internals 1.3.30 (was 1.3.22)
> cloud_firestore 4.17.0 (was 4.15.5)
> cloud_firestore_platform_interface 6.2.0 (was 6.1.6)
> cloud_firestore_web 3.12.0 (was 3.10.5)
> fake_cloud_firestore 2.4.9 (was 2.4.8)
> firebase_core 2.30.0 (was 2.25.4)
> firebase_core_web 2.15.0 (was 2.11.4)
  leak_tracker 10.0.0 (10.0.5 available)
  leak_tracker_flutter_testing 2.0.1 (3.0.5 available)
  leak_tracker_testing 2.0.1 (3.0.1 available)
> firefuel_core 0.1.3 (was 0.1.2)
  leak_tracker 10.0.0 (10.0.5 available)
  leak_tracker_flutter_testing 2.0.1 (3.0.5 available)
  leak_tracker_testing 2.0.1 (3.0.1 available)
  material_color_utilities 0.8.0 (0.11.1 available)
  meta 1.11.0 (1.14.0 available)
  rx 0.3.0 (0.4.0 available)
  test_api 0.6.1 (0.7.1 available)
> logger 2.2.0 (was 2.0.2+1)
  material_color_utilities 0.8.0 (0.11.1 available)
  meta 1.11.0 (1.14.0 available)
  rx 0.3.0 (0.4.0 available)
  test_api 0.6.1 (0.7.1 available)
  vm_service 13.0.0 (14.2.1 available)
> web 0.5.1 (was 0.4.2)
These packages are no longer being depended on:
- js 0.6.7

0.4.1

chore!: upgrade dependencies

• Environment
  • dart: 2.19.0 > 3.3.0
• Dependencies
  • cloud_firestore: 4.3.2 > 4.15.5

0.4.0

refactor!: renames count and streamCount to countAll and streamCountAll

This change was made to be more explicit, aligns with other methods such as readAll and streamAll, and leads us to look for other options like countWhere and streamCountWhere when using it in our apps.

BREAKING:

• count is now countAll
• streamCount is now streamCountAll

0.3.2

feat: adds a firefuel brick that can be used through Mason.

To install the firefuel brick, run mason add firefuel.

Afterwards, run mason get and mason make firefuel in the directory you'd like your FirefuelCollection and Model generated.

For more information, see the firefuel brick documentation or refer to the brick's README

0.3.1

feat: adds Firefuel.reset to clear internal property values without needing to re-initialize.

This is useful in teardown methods in your tests so you can ensure a clean state.

0.3.0

Adds count method

Adds count and countWhere to all Collections:

Uses the count feature introduced in v4.0.0 of cloud_firestore to count documents on the server without retrieving documents.

Firebase Release Notes

Cloud Firestore now supports a count() aggregation query that allows you to determine the number of documents in a collection. The server calculates the count, and transmits only the result, a single integer, back to your app, saving on both billed document reads and bytes transferred, compared to executing the full query.

Source: https://firebase.google.com/support/releases#firestore-count-queries

---

Adds streamCount and streamCountWhere to all Collections:

These methods DO NOT use the server side count function provided by v4.0.0 of cloud_firestore as they do not currenly support streams. These methods works by streaming documents from Firestore and accessing the size property once the full query is executed. This method will incur document reads and bytes transferred.

0.2.3

Our API has not changed so this is only a patch for firefuel. However, cloud_firestore and firebase_core both have breaking changes.

• chore: bump versions to align with latest cloud_firestore

General Upgrade Path from cloud_firestore 3 to 4

See the changelogs for cloud_firestore and firebase_core on pub.dev for more details.

---

Android

android>app>build.gradle: compileSdkVersion 31 minSdkVersion 19 targetSdkVersion 31

android>build.gradle: ext.kotlin_version = '1.6.10' classpath 'com.android.tools.build:gradle:7.1.2'

android>gradle>wrapper>gradle-wrapper.properties: distributionUrl=https\://services.gradle.org/distributions/gradle-7.2-bin.zip

android>app>src>main>AndroidManifest.xml: Add this attribute inside of the manifest>application>activity node android:exported="true"

---

iOS

ios>Podfile: platform :ios, '11.0'

Open your Flutter project in XCode and update the Minimum Deployment Target for the Runner Target to version 11.

cd into your ios directory and run pod update

0.2.2

• chore: bump versions to align with latest cloud_firestore

0.2.1

• fix: stack trace to show caught stack instead of creating a new one inside of the catch block

0.2.0

BREAKING chore: Upgrade Dependencies

• cloud_firestore v3.1.1:
  • BREAKING FEAT: update Android minSdk version to 19 as this is required by Firebase Android SDK 29.0.0 (#7298).

0.1.1

• feat: add web support
  • replace dart:io with universal_io

0.1.0+1

• docs: update readme

0.1.0

feat: Batches, filtering, and auto-gen docs!

• add ability to create batches with FirefuelBatch (#45)
• add whereById to FirefuelCollection (#48)
• add generateDocId to FirefuelCollection (#47)

0.0.2+2

• docs(fix): fix broken code in readme
  • update code example for model

0.0.2+1

• docs: update readme
  • add code example of creating a model and collection

0.0.2

• docs: update package links in pubspec
  • add homepage link
  • change repository link to direcly link to package
  • add documentation link

0.0.1

• feat: initial release