TurboFirestoreApi<T> class

A powerful, type-safe wrapper around Cloud Firestore operations.

The TurboFirestoreApi provides a high-level interface for interacting with Firestore, offering automatic type conversion, validation, and enhanced error handling.

Type parameter T represents the model type this API instance will work with.

Features:

Automatic type conversion between Firestore documents and Dart objects
Built-in validation through TurboWriteable
Automatic timestamp management for createdAt/updatedAt fields
Local ID management for easier document tracking
Sensitive data handling
Comprehensive logging
Collection group support
Batch operation capabilities

Example usage with a custom model:

class User {
  User({required this.name, this.age});

  final String name;
  final int? age;

  factory User.fromJson(Map<String, dynamic> json) => User(
    name: json['name'] as String,
    age: json['age'] as int?,
  );

  Map<String, dynamic> toJson() => {
    'name': name,
    'age': age,
  };
}

final api = TurboFirestoreApi<User>(
  firebaseFirestore: FirebaseFirestore.instance,
  collectionPath: () => 'users',
  fromJson: User.fromJson,
  toJson: (user) => user.toJson(),
);

// Create a new user
final user = User(name: 'John', age: 30);
await api.set(data: user);

// Query users
final adults = await api.query(
  where: (ref) => ref.where('age', isGreaterThanOrEqualTo: 18),
);

Available extensions

Constructors

TurboFirestoreApi.new({required FirebaseFirestore firebaseFirestore, required String collectionPath(), Map<String, dynamic> toJson(T value)?, T fromJson(Map<String, dynamic> json)?, T fromJsonError(Map<String, dynamic> json)?, bool tryAddLocalId = false, TurboFirestoreLogger? logger, String createdAtFieldName = 'createdAt', String updatedAtFieldName = 'updatedAt', String idFieldName = 'id', String documentReferenceFieldName = 'documentReference', bool isCollectionGroup = false, bool tryAddLocalDocumentReference = false, GetOptions? getOptions, bool hideSensitiveData = true}): Creates a new instance of TurboFirestoreApi.

Properties

collection → CollectionReference<Object?>: The current collection
no setter
doc → DocumentReference<Object?>: A new document
no setter
genId → String: Generates a new document ID without creating the document
no setter
hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
writeBatch → WriteBatch: Helper method to fetch a WriteBatch from _firebaseFirestore..
no setter

Methods

createDoc({required TurboWriteable writeable, String? id, WriteBatch? writeBatch, TurboTimestampType createTimeStampType = TurboTimestampType.createdAtAndUpdatedAt, TurboTimestampType updateTimeStampType = TurboTimestampType.updatedAt, bool merge = false, List<FieldPath>? mergeFields, String? collectionPathOverride, Transaction? transaction}) → Future<TurboResponse<DocumentReference<Object?>>>: Available on TurboFirestoreApi, provided by the TurboFirestoreCreateApi extension
Creates or writes a document to Firestore.
createDocInBatch({required TurboWriteable writeable, String? id, WriteBatch? writeBatch, TurboTimestampType createTimeStampType = TurboTimestampType.createdAtAndUpdatedAt, TurboTimestampType updateTimeStampType = TurboTimestampType.updatedAt, bool merge = false, List<FieldPath>? mergeFields, String? collectionPathOverride}) → Future<TurboResponse<WriteBatchWithReference<Map<String, dynamic>>>>: Available on TurboFirestoreApi, provided by the TurboFirestoreCreateApi extension
Creates or writes documents using a batch operation.
deleteDoc({required String id, WriteBatch? writeBatch, String? collectionPathOverride, Transaction? transaction}) → Future<TurboResponse>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreDeleteApi extension
Deletes a document from Firestore
deleteDocInBatch({required String id, WriteBatch? writeBatch, String? collectionPathOverride}) → Future<TurboResponse<WriteBatchWithReference<Map<String, dynamic>>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreDeleteApi extension
Deletes documents using a batch operation
docExists({required String id, String? collectionPathOverride}) → Future<bool>: Used to determined if a document exists based on given id.
getById({required String id, String? collectionPathOverride}) → Future<TurboResponse<Map<String, dynamic>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreGetApi extension
Retrieves a document by its unique identifier
getByIdWithConverter({required String id, String? collectionPathOverride}) → Future<TurboResponse<T>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreGetApi extension
Retrieves and converts a document by its unique identifier
getDocRefById({required String id, String? collectionPathOverride}) → DocumentReference<Map<String, dynamic>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreGetApi extension
Gets a document reference by ID for raw data access
getDocRefByIdWithConverter({required String id, String? collectionPathOverride}) → DocumentReference<T>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreGetApi extension
Gets a document reference with type conversion
getDocSnapshotById({required String id, String? collectionPathOverride}) → Future<DocumentSnapshot<Map<String, dynamic>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreGetApi extension
Gets a document snapshot for raw data access
getDocSnapshotByIdWithConverter({required String id, String? collectionPathOverride}) → Future<DocumentSnapshot<T>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreGetApi extension
Gets a document snapshot with type conversion
listAll() → Future<TurboResponse<List<Map<String, dynamic>>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreListApi extension
Lists all documents in the collection
listAllWithConverter() → Future<TurboResponse<List<T>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreListApi extension
Lists and converts all documents in the collection
listByQuery({required CollectionReferenceDef<Map<String, dynamic>> collectionReferenceQuery, required String whereDescription}) → Future<TurboResponse<List<Map<String, dynamic>>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreListApi extension
Lists documents matching a custom query
listByQueryWithConverter({required CollectionReferenceDef<T> collectionReferenceQuery, required String whereDescription}) → Future<TurboResponse<List<T>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreListApi extension
Lists and converts documents matching a custom query
listBySearchTerm({required String searchTerm, required String searchField, required TurboSearchTermType searchTermType, bool doSearchNumberEquivalent = false, int? limit}) → Future<TurboResponse<List<Map<String, dynamic>>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreSearchApi extension
Searches for documents matching a search term
listBySearchTermWithConverter({required String searchTerm, required String searchField, required TurboSearchTermType searchTermType, bool doSearchNumberEquivalent = false, int? limit}) → Future<TurboResponse<List<T>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreSearchApi extension
Searches for documents with type conversion
listCollectionReference() → Query<Map<String, dynamic>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreListApi extension
Gets a collection reference for raw data access
listCollectionReferenceWithConverter() → Query<T>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreListApi extension
Gets a collection reference with type conversion
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
runTransaction<E>(TransactionHandler<E> transactionHandler, {Duration timeout = const Duration(seconds: 30), int maxAttempts = 5}) → Future<E>: Helper method to run a Transaction from _firebaseFirestore..
streamAll() → Stream<QuerySnapshot<Map<String, dynamic>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreStreamApi extension
Streams all documents from a collection with exception handling
streamAllWithConverter() → Stream<List<T>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreStreamApi extension
Streams and converts all documents from a collection with error handling
streamByDocId({required String id, String? collectionPathOverride}) → Stream<DocumentSnapshot<Map<String, dynamic>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreStreamApi extension
Streams a single document
streamByQuery({required CollectionReferenceDef<Map<String, dynamic>>? collectionReferenceQuery, required String whereDescription}) → Stream<List<Map<String, dynamic>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreStreamApi extension
Streams documents matching a query
streamByQueryWithConverter({CollectionReferenceDef<T>? collectionReferenceQuery, required String whereDescription}) → Stream<List<T>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreStreamApi extension
Streams and converts documents matching a query
streamDocByIdWithConverter({required String id, String? collectionPathOverride}) → Stream<T?>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreStreamApi extension
Streams and converts a single document
toString() → String: A string representation of this object.
inherited
turboVars<V extends TurboApiVars>() → V: Returns a new instance of V with basic variables filled in.
updateDoc({required TurboWriteable writeable, required String id, WriteBatch? writeBatch, TurboTimestampType timestampType = TurboTimestampType.updatedAt, String? collectionPathOverride, Transaction? transaction}) → Future<TurboResponse<DocumentReference<Object?>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreUpdateApi extension
Updates an existing document in Firestore
updateDocInBatch({required TurboWriteable writeable, required String id, WriteBatch? writeBatch, TurboTimestampType timestampType = TurboTimestampType.updatedAt, String? collectionPathOverride}) → Future<TurboResponse<WriteBatchWithReference<Map<String, dynamic>>>>: Available on TurboFirestoreApi<T>, provided by the TurboFirestoreUpdateApi extension
Updates documents using a batch operation

Operators

operator ==(Object other) → bool: The equality operator.
inherited

TurboFirestoreApi<T> class

Constructors

Properties

Methods

Operators

turbo_firestore_api library