turbo_firestore_api library

A powerful and flexible Firestore API wrapper for Flutter applications

This package provides a type-safe, feature-rich interface for interacting with Cloud Firestore It includes support for CRUD operations, real-time updates, batch operations, and more

Features:

Type-safe document operations
Real-time data streaming
Batch and transaction support
Automatic timestamp management
Search capabilities
Collection group queries
Error handling and logging
Optimistic updates
Debouncing and mutex support
Authentication state synchronization

Example:

// Create a typed API instance
final api = TurboFirestoreApi<User>(
  collectionPath: 'users',
  fromJson: User.fromJson,
  toJson: (user) => user.toJson(),
);

// Create a document
final response = await api.createDoc(
  writeable: user,
  timestampType: TurboTimestampType.createdAndUpdated,
);

// Stream real-time updates
api.streamAllWithConverter().listen((users) {
  print('Got ${users.length} users');
});

See the individual components for detailed documentation:

Classes

AfterSyncTCollectionService<T extends TWriteableId, API extends TFirestoreApi<T>>: A collection service that allows notification after synchronizing data.
AfterSyncTDocumentService<T extends TWriteableId, API extends TFirestoreApi<T>>: A document service that allows notification after synchronizing data.
BeforeAfSyncTCollectionService<T extends TWriteableId, API extends TFirestoreApi<T>>: A collection service that allows notification both before and after synchronizing data.
BeforeAfterSyncTDocumentService<T extends TWriteableId, API extends TFirestoreApi<T>>: A document service that allows notification both before and after synchronizing data.
BeforeSyncTCollectionService<T extends TWriteableId, API extends TFirestoreApi<T>>: A collection service that allows notification before synchronizing data.
BeforeSyncTDocumentService<T extends TWriteableId, API extends TFirestoreApi<T>>: A document service that allows notification before synchronizing data.
TApiVars: An abstract class that defines the core variables required for Turbo Firestore documents.
TAuthErrors: Provides constants for various authentication-related error codes.
TAuthSyncService<StreamValue>: A service that synchronizes data with Firebase Authentication state changes.
TAuthVars: An abstract class that defines the core variables required for Turbo Firestore documents.
TCollectionService<T extends TWriteableId, API extends TFirestoreApi<T>>: A service for managing a collection of Firestore documents with synchronized local state.
TDocumentService<T extends TWriteableId, API extends TFirestoreApi<T>>: A service for managing a single Firestore document with synchronized local state.
TDummyFirestoreApi<T>: A drop-in replacement for TFirestoreApi that serves realistic fake data from an in-memory store without contacting Firestore.
TDummySchema: The output of the probing phase: a recursive description of an entity's field names, their resolved types or nested sub-schemas, and any fields that could not be resolved.
TDummySchemaBranch: A nested DTO field whose probing recursed into another fromJson invocation and produced its own sub-schema.
TDummySchemaField: A single field entry in a TDummySchema, representing either a flat resolved type or a nested DTO sub-schema.
TDummySchemaLeaf: A flat field whose resolved runtime type was determined by a successful cast during probing.
TErrorCodes: Constants for Firestore error codes and messages.
TFirestoreApi<T>: A powerful, type-safe wrapper around Cloud Firestore operations.
TFirestoreLogger: A logger for the TurboFirestoreApi that handles different log levels and sensitive data.
TSensitiveData: A model for encapsulating sensitive operation data for logging purposes
TValueGeneratorRegistry: Central value-resolution registry for dummy document generation.
TWriteBatchWithReference<T>: A container for a Firestore write batch and its most recently used document reference

Enums

TOperationType: Defines the type of Firestore operation being performed
TParseType
TSearchTermType: Defines the type of search operation to perform in Firestore queries
TTimestampType: Defines how timestamps should be managed in Firestore documents

Mixins

TExceptionHandler: A mixin that provides Firebase Authentication exception handling.
TFirestoreCreateApi<T>: Extension that adds create operations to TFirestoreApi
TFirestoreDeleteApi<T>: Extension that adds delete operations to TFirestoreApi
TFirestoreUpdateApi<T>: Extension that adds update operations to TFirestoreApi
TurboFirestoreGetApi<T>: Extension that adds read/get operations to TFirestoreApi
TurboFirestoreListApi<T>: Extension that adds list operations to TFirestoreApi
TurboFirestoreSearchApi<T>: Extension that adds search operations to TFirestoreApi
TurboFirestoreStreamApi<T>: Extension that adds stream operations to TFirestoreApi

Extensions

CompleterExtension on Completer<T>: Extension on Completer that provides additional utility methods for handling completion states.
TListExtensionExtension on List<T>: Extension on List that provides utility methods for working with lists in the context of Turbo Firestore.
TMapExtension on Map: Extension on Map that provides utility methods for working with Firestore documents.

Functions

addCollectionControllerForTesting<T>(TDummyFirestoreApi<T> api, StreamController<List<T>> controller) → void: Registers a collection stream controller for testing dispose behavior.
addDocControllerForTesting<T>(TDummyFirestoreApi<T> api, String id, StreamController<T?> controller) → void: Registers a document stream controller for testing dispose behavior.
applyDummyLatencyForTesting<T>(TDummyFirestoreApi<T> api) → Future<void>: Awaits the latency gate of a TDummyFirestoreApi instance.
applyDummyQueryFilterAndSortForTesting<T>(TDummyFirestoreApi<T> api, {required String? whereDescription, required List<Map<String, dynamic>> input}) → List<Map<String, dynamic>>: Exposes the query filter/sort seam for testing.
applyTimestampsForTesting<T>(TDummyFirestoreApi<T> api, {required Map<String, dynamic> json, required TTimestampType type}) → Map<String, dynamic>: Applies timestamps to a raw JSON map.
collectionControllerCountForTesting<T>(TDummyFirestoreApi<T> api) → int: Returns the number of active typed collection stream controllers.
docControllerCountForTesting<T>(TDummyFirestoreApi<T> api, String id) → int: Returns the number of active document stream controllers for id.
dummyDefaultCollectionSizeForTesting<T>(TDummyFirestoreApi<T> api) → int: Returns the default collection size for testing.
dummyPathSnapshotForTesting<T>(TDummyFirestoreApi<T> api) → String: Returns the path snapshot for testing.
dummyQueryFiltersForTesting<T>(TDummyFirestoreApi<T> api) → Map<String, bool Function(Map<String, dynamic>)>: Returns the query filters for testing.
dummyQuerySortForTesting<T>(TDummyFirestoreApi<T> api) → Map<String, int Function(Map<String, dynamic>, Map<String, dynamic>)>: Returns the query sort comparators for testing.
dummyRegistryForTesting<T>(TDummyFirestoreApi<T> api) → TValueGeneratorRegistry: Returns the value generator registry from a TDummyFirestoreApi instance.
dummySchemaForTesting<T>(TDummyFirestoreApi<T> api) → TDummySchema: Returns the probed schema from a TDummyFirestoreApi instance.
dummyStoreForTesting<T>(TDummyFirestoreApi<T> api) → Map<String, Map<String, dynamic>>: Returns the raw in-memory store for testing.
emitCollectionsForTesting<T>(TDummyFirestoreApi<T> api) → void: Re-emits the full store snapshot to every open collection controller.
emitDocForTesting<T>(TDummyFirestoreApi<T> api, String id, T? entity) → void: Re-emits a single document to every open controller for the given id.
fixed<V>(V value) → TValueGenerator: Returns a generator that always returns the exact supplied value.
futureDate({required Random random, Duration within = const Duration(days: 365)}) → TValueGenerator: Returns a generator that produces a DateTime after a deterministic anchor (DateTime.utc(2025)) within the given within duration on each call.
genDummyIdForTesting<T>(TDummyFirestoreApi<T> api) → String: Generates a deterministic dummy id from a TDummyFirestoreApi instance.
generateDocJsonForTesting<T>(TDummyFirestoreApi<T> api, {required String id}) → Map<String, dynamic>: Generates a raw JSON map for a document with the given id.
oneOf<V>(List<V> values, {required Random random}) → TValueGenerator: Returns a generator that picks a random element from values on each call.
oneOfEnum<E extends Enum>(List<E> values, {required Random random}) → TValueGenerator: Returns a generator that picks a random enum value from values on each call.
paragraph({required Random random, int sentences = 3}) → TValueGenerator: Returns a generator that produces a paragraph of sentences sentences on each call.
pastDate({required Random random, Duration within = const Duration(days: 365)}) → TValueGenerator: Returns a generator that produces a DateTime before a deterministic anchor (DateTime.utc(2025)) within the given within duration on each call.
probeDummySchemaForTesting<T>(T fromJson(Map<String, dynamic>)) → TDummySchema: Test-only entry point for the library-private _TDummyProbingMap.
rangeDouble(double min, double max, {required Random random}) → TValueGenerator: Returns a generator that produces a random double in [min, max) on each call.
rangeInt(int min, int max, {required Random random}) → TValueGenerator: Returns a generator that produces a random int in [min, max) on each call.
rawCollectionControllerCountForTesting<T>(TDummyFirestoreApi<T> api) → int: Returns the number of active raw collection stream controllers.
rollDummyFailureExceptionForTesting<T>(TDummyFirestoreApi<T> api, {required TOperationType operationType, String? id, Map<String, dynamic>? documentData}) → TFirestoreException?: Rolls a simulated failure exception from a TDummyFirestoreApi instance.
sentence({required Random random, int wordCount = 8}) → TValueGenerator: Returns a generator that produces a lowercase lorem sentence of wordCount words on each call.
uuid() → TValueGenerator: Returns a generator that produces deterministic pseudo-ids with a monotonically increasing counter.
words({required Random random, int min = 1, int max = 3}) → TValueGenerator: Returns a generator that produces between min and max (inclusive) lowercase lorem words joined by a space on each call.

Typedefs

CollectionReferenceDef<T> = Query<T> Function(Query<T> collectionReference): A function type for modifying Firestore collection queries.
CreateDocDef<T> = T Function(TAuthVars vars)
TLocatorDef<T> = T Function(): A function type for locating or creating instances of type T.
TValueGenerator = dynamic Function(): The callback contract every value provider in the dummy generator system implements.
UpdateDocDef<T> = T Function(T current, TAuthVars vars)
UpsertDocDef<T> = T Function(T? current, TAuthVars vars)

Exceptions / Errors

InvalidJsonException: Exception thrown when JSON data from Firestore is invalid or cannot be parsed
TFirestoreException: A sealed class for Firestore exceptions.
TurboFirestoreAlreadyExistsException: Exception thrown when a document already exists.
TurboFirestoreCancelledException: Exception thrown when an operation is cancelled.
TurboFirestoreDeadlineExceededException: Exception thrown when a deadline is exceeded.
TurboFirestoreGenericException: Generic Firestore exception for other error types.
TurboFirestoreNotFoundException: Exception thrown when a document is not found.
TurboFirestorePermissionDeniedException: Exception thrown when permission is denied for a Firestore operation.
TurboFirestoreUnavailableException: Exception thrown when a Firestore service is unavailable.

turbo_firestore_api library

Classes

Enums

Mixins

Extensions

Functions

Typedefs

Exceptions / Errors

turbo_firestore_api package

turbo_firestore_api library