firestore_helpers
library
Classes
-
Area
-
Defines the search area by a circle center / radiusInKilometers
Based on the limitations of FireStore we can only search in rectangles
which means that from this definition a final search square is calculated
that contains the circle
-
GeoBoundingBox
-
Defines the boundingbox for the query based
on its south-west and north-east corners
-
OrderConstraint
-
Used by buildQuery to define how the results should be ordered. The fields
corespond to the possisble parameters of Firestore`s
oderby()
method.
Using OrderConstraint almost always requires to create an index for this field. Check your debug output for a message from FireStore with
a link to create them
-
QueryConstraint
-
Used by buildQuery and getDataInArea to define a list of constraints. Important besides the field property not more than one of the others can ne
!=null
.
They corespond to the possisble parameters of Firestore`s where()
method.
Using QueryConstraint almost always requires to create an index for this field. Check your debug output for a message from FireStore with
a link to create them
Functions
-
boundingBoxCoordinates(Area area)
→ GeoBoundingBox
-
Calculates the SW and NE corners of a bounding box around a center point for a given radius;
area
with the center given as .latitude and .longitude
and the radius of the box (in kilometers)
-
buildQuery({required Query collection, List<QueryConstraint>? constraints, List<OrderConstraint>? orderBy})
→ Query
-
Builds a query dynamically based on a list of QueryConstraint and orders the result based on a list of OrderConstraint.
collection
: the source collection for the new query
constraints
: a list of constraints that should be applied to the collection
.
orderBy
: a list of order constraints that should be applied to the collection
after the filtering by constraints
was done.
Important all limitation of FireStore apply for this method two on how you can query fields in collections and order them.
-
coordinatesValid(double latitude, double longitude)
→ bool
-
Checks if these coordinates are valid geo coordinates.
latitude
The latitude must be in the range -90, 90
longitude
The longitude must be in the range -180, 180
returns true
if these are valid geo coordinates
-
degreesToRadians(double degrees)
→ double
-
-
distanceInKilometers(GeoPoint p1, GeoPoint p2)
→ double
-
Calculates the distance, in kilometers, between two locations, via the
Haversine formula. Note that this is approximate due to the fact that
the Earth's radius varies between 6356.752 km and 6378.137 km.
p1
The first location given
p2
The second location given
return the distance, in kilometers, between the two locations.
-
distanceInKilometers2(GeoPoint p1, GeoPoint p2)
→ double
-
-
geoPointValid(GeoPoint point)
→ bool
-
Checks if the coordinates of a GeopPoint are valid geo coordinates.
latitude
The latitude must be in the range -90, 90
longitude
The longitude must be in the range -180, 180
returns true
if these are valid geo coordinates
-
getDataFromQuery<T>({required Query query, required DocumentMapper<T> mapper, List<ItemFilter<T>>? clientSidefilters, ItemComparer<T>? orderComparer})
→ Stream<List<T>>
-
Convenience Method to access the data of a Query as a stream while applying
a mapping function on each document with optional client side filtering and sorting
qery
: the data source
mapper
: mapping function that gets applied to every document in the query.
Typically used to deserialize the Map returned from FireStore
clientSideFilters
: optional list of filter functions that execute a .where()
on the result on the client side
orderComparer
: optional comparisson function. If provided your resulting data
will be sorted based on it on the client
-
getDataInArea<T>({required Area area, required Query source, required DocumentMapper<T> mapper, required String locationFieldNameInDB, LocationAccessor<T>? locationAccessor, List<ItemFilter<T>>? clientSidefilters, DistanceMapper<T>? distanceMapper, DistanceAccessor<T>? distanceAccessor, bool sortDecending = false, List<QueryConstraint>? serverSideConstraints, List<OrderConstraint>? serverSideOrdering})
→ Stream<List<T>>
-
Provides as Stream of lists of data items of type
T
that have a location field in a
specified area sorted by the distance of to the areas center.
area
: The area that constraints the query
source
: The source FireStore document collection
mapper
: mapping function that gets applied to every document in the query.
Typically used to deserialize the Map returned from FireStore
locationFieldInDb
: The name of the data field in your FireStore document.
Need to make the location based search on the server side
locationAccessor
: As this is a generic function it cannot know where your
location is stored in you generic type.
optional if you don't use distanceMapper
and don't want to sort by distance
Therefore pass a function that returns a valur from the location field inside
your generic type.
distanceMapper
: optional mapper that gets the distance to the center of the
area passed to give you the chance to save this inside your item
if you use a distanceMapper
you HAVE to pass locationAccessor
clientSideFilters
: optional list of filter functions that execute a .where()
on the result on the client side
distanceAccessor
: if you have stored the distance using a distanceMapper
passing
this accessor function will prevent additional distance computing for sorting.
sortDecending
: if the resulting list should be sorted descending by the distance
to the area's center. If you don't provide loacationAccessor
or distanceAccessor
no sorting is done. This Sorting is done one the client side
serverSideConstraints
: If you need some serverside filtering besides the Area pass a list of QueryConstraint
serverSideOrdering
: If you need some serverside ordering you can pass a List of OrderConstraints
Using serverSideConstraints
or serverSideOrdering
almost always requires to create an index for
this field. Check your debug output for a message from FireStore with
a link to create them
-
getLocationsConstraint(String fieldName, Area area)
→ List<QueryConstraint>
-
Creates the necessary constraints to query for items in a FireStore collection that are inside a specific range from a center point
fieldName
: the name of the field in FireStore where the location of the items is stored
area
: Area within that the returned items should be
-
kilometersToLongitudeDegrees(double distance, double latitude)
→ double
-
Calculates the number of degrees a given distance is at a given latitude.
distance
The distance to convert.
latitude
The latitude at which to calculate.
returns the number of degrees the distance corresponds to.
-
wrapLongitude(double longitude)
→ double
-
Wraps the longitude to
-180,180
.
Typedefs
-
DistanceAccessor<T>
= double Function(T item)
-
function typse used to access the distance field that contains the
distance to the target inside the generic type
-
DistanceMapper<T>
= T Function(T item, double itemsDistance)
-
-
DocumentMapper<T>
= T? Function(DocumentSnapshot document)
-
-
ItemComparer<T>
= int Function(T item1, T item2)
-
-
ItemFilter<T>
= bool Function(T)
-
-
LocationAccessor<T>
= GeoPoint Function(T item)
-
function typse used to acces the field that contains the loaction inside
the generic type