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 documentId selectors.
ExecuteOptions
Options for executing a pipeline
FieldNode
A named field path (list of components). The document ID is represented by the special FieldPath.documentId in query positions.
FieldUpdate<T>
Per-field update handle for non-specialized fields: set and delete.
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 DocumentReference and 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) updates profile.followers only.
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 select projection.
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 update merge 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 update map keyed by FieldPath.
validateNumericRange(Object? value, {num? min, num? max, required String field}) → void
Throws when value is outside the @Min/@Max bounds of field.

Typedefs

AggregateField<T extends num?> = AggregateFieldSelector<T>
Deprecated name of AggregateFieldSelector; it collides with cloud_firestore's AggregateField in 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 FirebaseException with 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.