TFirestoreApi<T> class

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

The TFirestoreApi 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 TWriteable
• 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),
);

Mixed-in types

• TurboFirestoreGetApi<T>
• TurboFirestoreListApi<T>
• TFirestoreCreateApi<T>
• TFirestoreDeleteApi<T>
• TurboFirestoreSearchApi<T>
• TurboFirestoreStreamApi<T>
• TFirestoreUpdateApi<T>

Implementers

• TDummyFirestoreApi

Constructors

TFirestoreApi({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, TFirestoreLogger? logger, String createdAtFieldName = 'createdAt', String updatedAtFieldName = 'updatedAt', String idFieldName = 'id', String documentReferenceFieldName = 'documentReference', bool isCollectionGroup = false, bool tryAddLocalDocumentReference = false, GetOptions? getOptions})

Creates a new instance of TFirestoreApi.

Properties

collection → CollectionReference<Object?>

The current collection

no setter, inherited

doc → DocumentReference<Object?>

A new document

no setter, inherited

genId → String

Generates a new document ID without creating the document

no setter, inherited

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

writeBatch → WriteBatch

Helper method to fetch a WriteBatch from _firebaseFirestore..

no setter, inherited

Methods

createDoc({required TWriteable writeable, String? id, WriteBatch? writeBatch, TTimestampType createTimeStampType = TTimestampType.createdAtAndUpdatedAt, TTimestampType updateTimeStampType = TTimestampType.updatedAt, bool merge = false, List<FieldPath>? mergeFields, String? collectionPathOverride, Transaction? transaction}) → Future<TurboResponse<DocumentReference<Object?>>>

Creates or writes a document to Firestore.

inherited

createDocInBatch({required TWriteable writeable, String? id, WriteBatch? writeBatch, TTimestampType createTimeStampType = TTimestampType.createdAtAndUpdatedAt, TTimestampType updateTimeStampType = TTimestampType.updatedAt, bool merge = false, List<FieldPath>? mergeFields, String? collectionPathOverride}) → Future<TurboResponse<TWriteBatchWithReference<Map<String, dynamic>>>>

Creates or writes documents using a batch operation.

inherited

deleteDoc({required String id, WriteBatch? writeBatch, String? collectionPathOverride, Transaction? transaction}) → Future<TurboResponse<void>>

Deletes a document from Firestore

inherited

deleteDocInBatch({required String id, WriteBatch? writeBatch, String? collectionPathOverride}) → Future<TurboResponse<TWriteBatchWithReference<Map<String, dynamic>>>>

Deletes documents using a batch operation

inherited

dispose() → Future<void>

Releases resources held by this API instance.

inherited

docExists({required String id, String? collectionPathOverride}) → Future<bool>

Used to determined if a document exists based on given id.

inherited

getById({required String id, String? collectionPathOverride}) → Future<TurboResponse<Map<String, dynamic>>>

Retrieves a document by its unique identifier

inherited

getByIdWithConverter({required String id, String? collectionPathOverride}) → Future<TurboResponse<T>>

Retrieves and converts a document by its unique identifier

inherited

getDocRefById({required String id, String? collectionPathOverride}) → DocumentReference<Map<String, dynamic>>

Gets a document reference by ID for raw data access

inherited

getDocRefByIdWithConverter({required String id, String? collectionPathOverride}) → DocumentReference<T>

Gets a document reference with type conversion

inherited

getDocSnapshotById({required String id, String? collectionPathOverride}) → Future<DocumentSnapshot<Map<String, dynamic>>>

Gets a document snapshot for raw data access

inherited

getDocSnapshotByIdWithConverter({required String id, String? collectionPathOverride}) → Future<DocumentSnapshot<T>>

Gets a document snapshot with type conversion

inherited

listAll() → Future<TurboResponse<List<Map<String, dynamic>>>>

Lists all documents in the collection

inherited

listAllWithConverter() → Future<TurboResponse<List<T>>>

Lists and converts all documents in the collection

inherited

listByQuery({required CollectionReferenceDef<Map<String, dynamic>> collectionReferenceQuery, required String whereDescription}) → Future<TurboResponse<List<Map<String, dynamic>>>>

Lists documents matching a custom query

inherited

listByQueryWithConverter({required CollectionReferenceDef<T> collectionReferenceQuery, required String whereDescription}) → Future<TurboResponse<List<T>>>

Lists and converts documents matching a custom query

inherited

listBySearchTerm({required String searchTerm, required String searchField, required TSearchTermType searchTermType, bool doSearchNumberEquivalent = false, int? limit}) → Future<TurboResponse<List<Map<String, dynamic>>>>

Searches for documents matching a search term

inherited

listBySearchTermWithConverter({required String searchTerm, required String searchField, required TSearchTermType searchTermType, bool doSearchNumberEquivalent = false, int? limit}) → Future<TurboResponse<List<T>>>

Searches for documents with type conversion

inherited

listCollectionReference() → Query<Map<String, dynamic>>

Gets a collection reference for raw data access

inherited

listCollectionReferenceWithConverter() → Query<T>

Gets a collection reference with type conversion

inherited

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..

inherited

streamAll() → Stream<QuerySnapshot<Map<String, dynamic>>>

Streams all documents from a collection with exception handling

inherited

streamAllWithConverter() → Stream<List<T>>

Streams and converts all documents from a collection with error handling

inherited

streamByDocId({required String id, String? collectionPathOverride}) → Stream<DocumentSnapshot<Map<String, dynamic>>>

Streams a single document

inherited

streamByQuery({required CollectionReferenceDef<Map<String, dynamic>>? collectionReferenceQuery, required String whereDescription}) → Stream<List<Map<String, dynamic>>>

Streams documents matching a query

inherited

streamByQueryWithConverter({CollectionReferenceDef<T>? collectionReferenceQuery, required String whereDescription}) → Stream<List<T>>

Streams and converts documents matching a query

inherited

streamDocByIdWithConverter({required String id, String? collectionPathOverride}) → Stream<T?>

Streams and converts a single document

inherited

toString() → String

A string representation of this object.

inherited

turboVars<V extends TApiVars>() → V

Returns a new instance of V with basic variables filled in.

inherited

updateDoc({required TWriteable writeable, required String id, WriteBatch? writeBatch, TTimestampType timestampType = TTimestampType.updatedAt, String? collectionPathOverride, Transaction? transaction}) → Future<TurboResponse<DocumentReference<Object?>>>

Updates an existing document in Firestore

inherited

updateDocInBatch({required TWriteable writeable, required String id, WriteBatch? writeBatch, TTimestampType timestampType = TTimestampType.updatedAt, String? collectionPathOverride}) → Future<TurboResponse<TWriteBatchWithReference<Map<String, dynamic>>>>

Updates documents using a batch operation

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited