Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mrbandler/FsFirestore
Functional F# library to access Firestore database hosted on Google Cloud Platform (GCP) or Firebase.
https://github.com/mrbandler/FsFirestore
base cloud core dotnet fire firebase firebase-database firestore fs fsfirestore fsharp gcp google platform store
Last synced: 4 months ago
JSON representation
Functional F# library to access Firestore database hosted on Google Cloud Platform (GCP) or Firebase.
- Host: GitHub
- URL: https://github.com/mrbandler/FsFirestore
- Owner: mrbandler
- License: mit
- Created: 2018-10-15T19:20:09.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-04-11T20:08:10.000Z (about 3 years ago)
- Last Synced: 2024-02-27T18:28:23.998Z (4 months ago)
- Topics: base, cloud, core, dotnet, fire, firebase, firebase-database, firestore, fs, fsfirestore, fsharp, gcp, google, platform, store
- Language: F#
- Homepage:
- Size: 216 KB
- Stars: 25
- Watchers: 3
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- awesome-fsharp - FsFirestore - Functional F# library to access Firestore database hosted on Google Cloud Platform (GCP) or Firebase. [MIT] (Cloud)
README
# FsFirestore
[](https://github.com/mrbandler/FsFirestore/actions)
[](https://www.nuget.org/packages/FsFirestore)
[](https://en.cryptobadges.io/donate/3LTBGYAHQCDE4ZbEiTreJjzgnsDhY6X2D2)
[](https://en.cryptobadges.io/donate/LcHsJH13A8PmHJQwpbWevGUebZwhWNMXgS)
[](https://en.cryptobadges.io/donate/0x54499ee409687E9C43589693093D004a0cbfEE72)
[](https://www.paypal.me/mrbandler/)
**Functional F# library to access Firestore database hosted on Google Cloud Platform (GCP) or Firebase.**
## Table Of Content
1. [Usage](#1-usage) ⌨️
2. [Bugs and Features](#2-bugs-and-features) 🐞💡
3. [Buy me a coffee](#3-buy-me-a-coffee) ☕
4. [License](#4-license) 📃
---
## 1. Usage
### Connect to Firestore
To use any of the Firestore features you have to initialize the connection via a Service Account JSON (either for [Firebase](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk) or [GCP](https://cloud.google.com/docs/authentication/getting-started)).
There are four ways to connect to your Firestore instance.
#### 1. Service Account JSON Path
```fsharp
open FsFirestore.Firestore
let connected = connectToFirestore "./path/to/your/service_account.json"
```
The `connectToFirestore` function returns a boolean, to indicate whether the connection could be established.
#### 2. Project ID
Set the path to your service account JSON to the environment variable `GOOGLE_APPLICATION_CREDENTIALS` and use your project ID to connect.
```fsharp
open FsFirestore.Firestore
connectToFirestoreProject "your_project_id"
```
#### 3. Service Account JSON Path & DB Builder
Use a DB builder to connect, this lets you specify additional settings such as Custom Converters (example below).
```fsharp
open FsFirestore.Firestore
open Google.Cloud.Firestore
// Player ID.
type PlayerId (id: string) =
let id = id
member this.Id with get () = id
// Custom player ID converter.
type PlayerIdConverter () =
interface IFirestoreConverter with
member this.ToFirestore value = value.Id :> obj
member this.FromFirestore value =
match value with
| :? string as id -> PlayerId id
| _ -> PlayerId ""
// Use custom type with custom converter.
[]
type Game () =
inherit FirestoreDocument()
[]
member val PlayerA = PlayerId "0"
[]
member val PlayerB = PlayerId "1"
// connect :: Unit -> Boolean
let connect () =
let converter = PlayerIdConverter ()
let registry = ConverterRegistry ()
registry.Add converter
let builder = FirestoreDbBuilder ()
builder.ConverterRegistry <- registry
builder |> connectToFirestoreWithBuilder "./path/to/your/service_account.json"
```
#### 4. DB Builder Only
Set the path to your service account JSON to the environment variable `GOOGLE_APPLICATION_CREDENTIALS` and use your project ID to connect.
```fsharp
open FsFirestore.Firestore
open Google.Cloud.Firestore
let builder = FirestoreDbBuilder ()
builder.ProjectId <- "your_project_id"
builder |> connectToFirestoreWithBuilderOnly
```
### Create, Read, Update and Delete (CRUD)
After your successfully connected to your Firestore you can start manipulating data.
#### Model Classes
For better handling within the API we added generic retrieval functions, to simply retrieve your wanted model. Sadly the Google .NET API only let's us use classes, to compensate we created a base class that can be used to make your life easier. For a detailed description on data models for Firebase read [this](http://googleapis.github.io/google-cloud-dotnet/docs/Google.Cloud.Firestore/datamodel.html).
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Types
[]
type Address() =
inherit FirestoreDocument() // Base class that comes with FsFirestore
[]
member val Street = "Pennsylvania Avenue" with get, set
[]
member val HouseNo = 1600 with get, set
[]
member val City = "Washington" with get, set
[]
member val State = "DC" with get, set
// Because of the inheritance we now have some niffty features in this straight forward model class.
let address = new Address()
// We can retrieve all fields in a object list,
// which can later be used to query Firestore.
let fields = address.AllFields // => ["Pennsylvania Avenue"; 1600; "Washington"; "DC"]
let specificField = address.Fields("HouseNo", "City") // => [1600; "Washington"]
// We can ask the model which ID and collection it belongs to.
let docId = address.Id
let collectionId = address.CollectionId
```
#### Reading Documents
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Firestore
// Let's read an address from Firestore and
// automatically convert it to our model.
let address = document
"addresses" "POTUS-address"
// Again if your model inherits from "FirestoreDocument"
// you can use these features.
let docId = address.Id // => "POTUS-address""
let collectionId = address.CollectionId // => "addresses""
// --- or ---
// Let's just retrieve the document reference...
let addressRef = documentRef "addresses" "POTUS-address"
// And convert it to our model class manually.
let address = convertTo
addressRef
// Again if your model inherits from "FirestoreDocument"
// you can use these features.
let docId = address.Id // => "POTUS-address""
let collectionId = address.CollectionId // => "addresses""
// --- or to check if a document exists ---
// Let's retrieve a document snapshot.
let addressSnap = documentSnapshot "addresses" "POTUS-address"
// Then you can check if a snapshot exists.
let exists = addressSnap.Exists // => true, false
```
#### Querying Documents
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Firestore
open FsFirestore.Query
// To query a collection we first need to retrieve it from Firestore
let queryCollection = collection "addresses"
// Now we can chain conditions.
// Let's query all addresses in Pennsylvania Avenue, DC up to POTUS's one.
let addresses =
queryCollection
|> orderBy "HouseNo"
|> whereEqualTo "State" "DC"
|> whereEqualTo "Street" "Pennsylvania Avenue"
|> whereGreaterThenOrEqualTo "HouseNo" 1
|> whereLessThenOrEqualTo "HouseNo" 1600
|> execQuery
```
#### Writing Documents
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Firestore
// Let's create the model that we want to add to Firestore
let address = new Address()
// Now we can add the address to Firestore with a given
// collection name and ID.
let docRef = addDocument "addresses" (Some "POTUS-address") address
// -- or --
// We can also add the address and let the ID be generated automatically.
let docRef = addDocument "addresses" None address
```
#### Updating Documents
```fsharp
open FsFirestore.Firestore
// We can first the read the document we want to update
// from Firestore.
let address = document
"addresses" "POTUS-address"
// Now let's move the presidents house number along one number.
address.HouseNo <- 1601
// And update the document within Firestore.
let docRef = updateDocument "addresses" "POTUS-address" address
```
#### Deleting Documents
```fsharp
open FsFirestore.Firestore
// To delete a document we simply need the collection ID
// and the document ID.
deleteDocument None "addresses" "POTUS-address"
// -- or --
// Additionally we can specify a precondition for the deletion process.
let timeStamp = Timestamp.FromDateTime(DateTime.Today)
let precondition = Precondition.LastUpdated(timeStamp)
deleteDocument precondition "addresses" "POTUS-address"
```
### Transactions
Transactions are functions which take in a `Transaction` object to create, read, update, delete and query documents within the transaction scope.
##### Reading Documents in Transaction
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Transaction
// Reading a document works just as expected only with the minor difference
// to use the transaction specific function from the Transaction module.
let transactionFunc (trans: Transaction) =
documentInTrans
trans "addresses" "POTUS-address"
// Now let's run the transaction.
// Notice that the transaction will return the return value from the actual transaction
// function.
let address = runTransaction transactionFunc
// -- or --
// You can specify the return values type, but F# will detected the type automatically
// most of the time.
let address = runTransaction
transactionFunc
```
##### Writing Documents in Transaction
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Transaction
// Let's create the model that we want to add to Firestore
let address = new Address()
// Now let's write a transaction to add an address to Firestore with a given
// collection name and ID.
let transactionFunc (trans: Transaction) =
addDocumentInTrans trans "addresses" (Some "POTUS-address") address
// Let's run the transaction.
let docRef = runTransaction transactionFunc
// -- or --
// Of course, we can also add the address and let the ID be generated automatically.
let transactionFunc (trans: Transaction) =
addDocumentInTrans trans "addresses" None address
```
##### Updating Documents in Transaction
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Firestore
// Let's create our update transaction.
let transactionFunc (trans: Transaction) =
// We can first read the document we want to update
// from Firestore.
let address = documentInTrans
trans "addresses" "POTUS-address"
// Now let's move the presidents house number along one number.
address.HouseNo <- 1601
// And update the document.
updateDocumentInTrans trans "addresses" "POTUS-address" address
// Let's run the transaction.
let docRef = runTransaction transactionFunc
```
##### Deleting Documents in Transaction
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Firestore
// Let's create our deletion transaction.
let transactionFunc (trans: Transaction) =
// To delete a document we simply need the collection ID
// and the document ID.
deleteDocumentInTrans trans None "addresses" "POTUS-address"
// Let's run the transaction.
runTransaction transactionFunc
// -- or --
// As mentioned in the CRUD section we can also specify a precondition
// for the deletion process.
let transactionFunc (trans: Transaction) =
let timeStamp = Timestamp.FromDateTime(DateTime.Today)
let precondition = Precondition.LastUpdated(timeStamp)
deleteDocumentInTrans trans precondition "addresses" "POTUS-address"
runTransaction transactionFunc
```
### Listening for Changes
Firestore provides the ability to use a streaming API that let's you listen to changes made do specific documents or a complete set of documents managed by a query.
The listener functions will be called on document creation, deletion and update. You can even specify a listener functions for none existing documents, this requires a named document ID before hand.
#### Data Definition
For the listening examples we will use different model classes.
```fsharp
open Google.Cloud.Firestore
open FsFirestore.Types
// Stores scores per user, the username will be the document ID.
[]
type Score() =
inherit FirestoreDocument() // Base class that comes with FsFirestore
[]
member val BestScore = 0 with get, set
[]
member val LastScore = 0 with get, set
// Stores a list of usernames that have high scores.
// A highscore is any score above 1000.
[]
type HighScores() =
inherit FirestoreDocument() // Base class that comes with FsFirestore
[]
member val Usernames = [] with get, set
```
#### Mounting Listeners
```fsharp
open FsFirestore.Firestore
open FsFirestore.Listening
// To creater a listener it's as easy as writing a simple function,
// as it practically is just a function.
let callback (snap: DocumentSnapshot) =
if snap.Exists = true then
// The callback takes in a document snapshot, we can convert the snap
// to our model.
let score = convertSnapshotTo snap
// Now we can use the listener to set the best score to the last score
// if it was better then the current best score.
if score.LastScore > score.BestScore then
score.BestScore <- score.LastScore
updateDocument score.CollectionId score.Ids score
// Now we can simple mount our created listener callback and in
// turn receive a listener object from Firestore
let listener = listenOnDocument "scores" "mrbandler" callback
// If we want to stop listening we just stop listening.
stopListening listener
```
#### Listening For Query Changes
```fsharp
open FsFirestore.Firestore
open FsFirestore.Listening
// Now we can use a listener to update a different document with the
// best high scores.
let callback (querySnap: QuerySnapshot) =
// If the query changes the callback is called and we can retrieve the
// updated query results.
let scores = convertSnapshotsTo querySnap.Documents |> List.ofSeq
// Now we can extract the usernames from the scores into an array.
let usernames =
scores
|> List.map (fun score -> score.Id)
|> Array.ofList
// Let's update our highscores document with the new usernames.
let highScores = document "highscores" "users"
highScores.Usernames <- usernames
updateDocument highScores.CollectionId highScores.Id highScores
// Now let's mount our created listener callback to a query.
// We only want highscores that are above 1000, to be neat we also order them.
let listener =
collection "scores"
|> whereGreaterThen "BestScore" 1000
|> orderBy "BestScore"
|> listenOnQuery callback
// If we want to stop listening we just stop listening.
stopListening listener
```
In the above example we a simply retrieving all documents from the query which can be a lot of data. There is a way to only work with the changes from the query.
```fsharp
open FsFirestore.Firestore
open FsFirestore.Listening
// Now we can use a listener to update a different document with the
// best high scores.
let callback (querySnap: QuerySnapshot) =
// If the query changes the callback is called and we can retrieve the
// updated query results.
let scoreChanges = convertQueryChanges querySnap.Changes |> List.ofSeq
// A document change contains a bit more data then a usual document
let scoreChange = List.item 0
let doc = scoreChange.document // => Actuall converted document data
let changeType = scoreChange.changeType // => Added (there also is Updated and Removed)
let newIndex = scoreChange.newIndex // => New index (option) if moved in the query
let oldIndex = scoreChange.oldIndex // => Old index (option) if moved in the query
// Now we can extract the usernames from the scores into an array.
let usernames =
scoreChanges
|> List.filter (fun scoreChange -> scoreChange.changeType = DocumentChange.Type.Added)
|> List.map (fun scoreChange -> scoreChange.document.Id)
|> Array.ofList
// Let's update our highscores document with the new usernames.
let highScores = document "highscores" "users"
Array.append highScores.Usernames usernames // Now instead of overwriting the all usernames we add to the array.
updateDocument highScores.CollectionId highScores.Id highScores
// Now let's mount our created listener callback to a query.
// We only want highscores that are above 1000, to be neat we also order them.
let listener =
collection "scores"
|> whereGreaterThen "BestScore" 1000
|> orderBy "BestScore"
|> listenOnQuery callback
// If we want to stop listening we just stop listening.
stopListening listener
```
## 2. Bugs and Features
Please open a issue when you encounter any bugs 🐞 or have an idea for a new feature 💡.
## 3. Buy me a coffee
If you like you can buy me a coffee:
[](https://www.paypal.me/mrbandler/)
[](https://en.cryptobadges.io/donate/3LTBGYAHQCDE4ZbEiTreJjzgnsDhY6X2D2)
[](https://en.cryptobadges.io/donate/LcHsJH13A8PmHJQwpbWevGUebZwhWNMXgS)
[](https://en.cryptobadges.io/donate/0x54499ee409687E9C43589693093D004a0cbfEE72)
---
## 4. License
MIT License
Copyright (c) 2018 fivefingergames
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.