firestore_odm library
Type-safe Firestore ODM for Dart/Flutter — code generation, zero
reflection, exact Firestore semantics (see docs/adr/0002).
Classes
- AggregateBuilderContext
- AggregateBuilderRoot
-
Root of a generated aggregate builder; provides
count(). - AggregateContext
- Context that records the aggregate operations of an aggregate builder.
-
AggregateFieldSelector<
T extends num?> - Typed aggregate selector for one numeric field.
- AggregateOperation
- Base class for aggregate operations.
-
AggregateQuery<
R extends Record, AB extends AggregateBuilderRoot> - The result of an aggregate query; one-shot only.
- AggregateResultContext
- ArrayRemoveOperation
- Atomically removes values from the array at field.
- ArrayUnionOperation
- Atomically adds values to the array at field (deduplicated server-side).
- AverageOperation
-
BatchCollection<
S extends FirestoreSchema, T, P extends PatchBuilder< T> > - Typed batch writes for one collection.
-
BatchContext<
S extends FirestoreSchema> - A batch write context. Writes are queued and committed together.
-
BatchDocument<
S extends FirestoreSchema, T, P extends PatchBuilder< T> > - Typed batch writes for one document.
- BooleanExpression
- Base class for boolean expressions used in filtering
-
Collection<
T> - Annotation to define a Firestore collection in a schema
- CountOperation
- DateTimeFieldUpdate
- DateTime fields additionally support server timestamps.
- DeleteOperation
- Deletes field.
- DocumentIdField
- Annotation to mark a field as the document ID This field will be synchronized with the Firestore document ID but will not be included in the document content.
- DocumentIdNode
-
The document-ID pseudo-field used by generated
documentIdselectors. - ExecuteOptions
- Options for executing a pipeline
- FieldNode
-
A named field path (list of components). The document ID is represented by
the special
FieldPath.documentIdin query positions. -
FieldUpdate<
T> -
Per-field update handle for non-specialized fields:
setanddelete. - FilterBuilderRoot
- Base class for generated filter builders; carries the path prefix.
-
FilterField<
T, E> - A typed filter selector for a single field.
- FilterOperation
-
A composable filter operation backed by a native
firestore.Filter. -
FirestoreBuilder<
Snapshot> - Listens to a typed reference and builds a widget from its latest value.
-
FirestoreCollection<
S extends FirestoreSchema, T, P extends PatchBuilder< T> , F extends FilterBuilderRoot, OB extends OrderByBuilderRoot, AB extends AggregateBuilderRoot> - A type-safe wrapper around a Firestore collection reference.
-
FirestoreDocument<
S extends FirestoreSchema, T, P extends PatchBuilder< T> > - A type-safe wrapper around a Firestore document reference.
-
FirestoreListenable<
Snapshot> - A typed reference whose latest value can be watched: something a FirestoreBuilder can listen to.
-
FirestoreODM<
S extends FirestoreSchema> - Main ODM class. Create one per schema:
- FirestoreOdm
- FirestoreSchema
- Marker base class for ODM schemas.
- GetOptions
-
An options class that configures the behavior of get() calls on
DocumentReferenceand Query. - IncrementOperation
- Atomically increments the numeric value at field by delta.
-
ListFieldUpdate<
T> - List fields additionally support atomic array union/remove.
- Max
- Constrains a numeric field to a maximum value.
- Min
- Constrains a numeric field to a minimum value.
-
NumericFieldUpdate<
T extends num> -
Numeric fields additionally support atomic
increment. - OrderByBuilderContext
- OrderByBuilderRoot
- Base class for generated orderBy builders.
- OrderByContext
- Context that records the fields selected by an orderBy builder.
- OrderByExtractor
- Extracts cursor values from a model object for the given orderBy terms.
-
OrderByField<
T> - A typed orderBy selector for one field. Calling it records the term in the context and returns a dummy value so the user's record literal type-checks.
- OrderByFieldInfo
- A single orderBy term.
-
OrderedQuery<
S extends FirestoreSchema, T, O extends Record, P extends PatchBuilder< T> , F extends FilterBuilderRoot, OB extends OrderByBuilderRoot, AB extends AggregateBuilderRoot> - A typed ordered query with pagination.
- Ordering
- Represents an ordering specification for pipeline sorting
-
PatchBuilder<
T> -
Base class for generated patch builders. A builder is a path namespace:
field is empty for the document itself and the field path for a nested
model (
$.profile), so$.profile.followers.increment(1)updatesprofile.followersonly. - Pipeline
- A pipeline for querying and transforming Firestore data.
- PipelineContext
- Dual-phase context for shape-changing stages (select/aggregate): a capture pass records the native expressions under deterministic aliases, a result pass replays the same record builder against each result row.
-
PipelineField<
T> - A type-safe leaf for a scalar field; produces native pipeline expressions/orderings/aggregates from the field path — never a string.
- PipelineFieldNode
-
Base class for generated pipeline selectors; carries the path prefix and an
optional capture context (present inside
select/aggregate). - PipelineResult
- Represents the results of a Pipeline query, including the data and metadata.
- PipelineSnapshot
- A PipelineSnapshot contains the results of a pipeline execution. It can be iterated to retrieve the individual PipelineResult objects.
-
ProjectedPipeline<
R> -
The result of a
selectprojection. -
Query<
S extends FirestoreSchema, T, P extends PatchBuilder< T> , F extends FilterBuilderRoot, OB extends OrderByBuilderRoot, AB extends AggregateBuilderRoot> - A typed Firestore query.
- QueryAggregatableHandler
- Builds and applies aggregate terms from a generated builder.
- QueryFilterHandler
- Applies a built filter to a native query.
- QueryOrderbyHandler
- Builds and applies orderBy terms from a generated builder.
- QueryPaginationHandler
- Schema
- Annotation to mark a variable as a Firestore schema definition
- SelectorRoot
- The root of any generated selector tree; carries the path prefix.
- ServerTimestampOperation
- Sets field to the server timestamp at write time.
- SetOperation
-
Sets value at field. Top-level fields are replaced; nested map paths
follow Firestore's native
updatemerge semantics. - SumOperation
-
TransactionCollection<
S extends FirestoreSchema, T, P extends PatchBuilder< T> > - Typed transactional writes for one collection.
-
TransactionContext<
S extends FirestoreSchema> -
A transaction context. Constructed by FirestoreODM.runTransaction; typed
handles come from
collection.inTransaction(context). -
TransactionDocument<
S extends FirestoreSchema, T, P extends PatchBuilder< T> > - Typed transactional access to one document.
-
TypedPipeline<
T, S extends PipelineFieldNode> - Type-safe wrapper over a Firestore firestore.Pipeline preserving the model element type.
- UpdateOperation
- A single patch operation applied at field (a dotted path relative to the document).
Enums
- Source
- An enumeration of firestore source types.
Extensions
- FilterOperationComposition on FilterOperation
- RecordToListExtension on Record
- Extension for converting Dart Records to List.
Constants
- firestoreOdm → const FirestoreOdm
- kFirestoreMaxWritesPerBatch → const int
- Firestore's maximum number of writes per batch/transaction.
Functions
-
dateTimeFromJson(
Object? value) → DateTime - Converts a stored Timestamp (or DateTime, as returned by test doubles) back to DateTime.
-
defaultValue<
T> () → T - Returns a sensible dummy value for capture contexts (orderBy/aggregate record builders). The value is never written to Firestore.
-
durationFromJson(
Object? value) → Duration - Converts a stored microseconds int back to Duration.
-
durationToJson(
Duration value) → Object? - Converts a Duration to Firestore microseconds (int).
-
identity<
T> (T value) → T - Identity value converter (primitives, DateTime, Timestamp, GeoPoint, Blob, DocumentReference — everything Firestore stores natively).
-
operationsToMap(
List< UpdateOperation> operations) → Map<Object, Object?> -
Converts patch operations to the native
updatemap keyed byFieldPath. -
validateNumericRange(
Object? value, {num? min, num? max, required String field}) → void -
Throws when
valueis outside the@Min/@Maxbounds offield.
Typedefs
-
AggregateField<
T extends num?> = AggregateFieldSelector< T> -
Deprecated name of AggregateFieldSelector; it collides with
cloud_firestore's
AggregateFieldin files that import both. -
FieldFromJson<
T> = T Function(dynamic value) - Converts a single Firestore wire value to the Dart field type.
-
FieldToJson<
T> = dynamic Function(T value) - Converts a single field value to its Firestore wire representation.
-
JsonDeserializer<
T> = T Function(Map< String, dynamic> json) - Deserializes a Firestore document map into a model instance.
-
JsonSerializer<
T> = Map< String, dynamic> Function(T value) - Serializes a model instance into the Firestore document map.
Exceptions / Errors
- FirestoreODMDocumentException
- Raised when a document-level operation fails (missing document, malformed snapshot, wrapped platform error).
- FirestoreODMException
- FirestoreODMPathException
- Raised when a nested field path cannot be resolved on a document map.
- FirestoreODMPlatformException
-
Wraps a platform
FirebaseExceptionwith ODM context while preserving the original code and message so existing Firebase-style handling keeps working. - FirestoreODMTypeException
- Raised when a Firestore value does not match the expected Dart type.
- FirestoreODMValidationException
- Raised when a document or its data fails validation.