IzumiSy / elm-firestore / Firestore

A library to have your app interact with Firestore in Elm


type Firestore

Data type for Firestore.

Constructors

init : Config -> Firestore

Builds a new Firestore connection with Config.

withConfig : Config -> Firestore -> Firestore

Updates configuration.

Path


type Path type_

A validated path type

An instance of this type can be constructed with build function. CRUDs function can accept this type to run their opration as follows.

firestore
    |> Firestore.root
    |> Firestore.collection "users"
    |> Firestore.document "user0"
    |> Firestore.subCollection "tags"
    |> Firestore.build
    |> ExResult.toTask
    |> Task.andThen (Firestore.list tagDecoder ListOptions.default)
    |> Task.attempt GotUserItemTags

root : Firestore -> PathBuilder RootType

A root path

collection : String -> PathBuilder RootType -> PathBuilder CollectionType

A collection path

subCollection : String -> PathBuilder DocumentType -> PathBuilder CollectionType

A sub-collection path

document : String -> PathBuilder CollectionType -> PathBuilder DocumentType

A document path

build : PathBuilder a -> Result Error (Path a)

Validates PathBuilder and converts it into Path if it is valid.

CRUDs


type alias Document a =
{ name : Name
, fields : a
, createTime : Time.Posix
, updateTime : Time.Posix 
}

A record structure for a document fetched from Firestore.


type alias Documents a =
{ documents : List (Document a)
, nextPageToken : Maybe Options.List.PageToken 
}

A record structure composed of multiple documents fetched from Firestore.


type Name

Name field of Firestore document

id : Name -> String

Extracts ID from Name field

get : Decoder a -> Path (DocumentPath b) -> Task Error (Document a)

Gets a single document.

list : Decoder a -> Options.List.Options -> Path (CollectionPath b) -> Task Error (Documents a)

Lists documents.

create : Decoder a -> { id : String, document : Encoder } -> Path (CollectionPath b) -> Task Error (Document a)

Creates a document with a given document id.

Takes the document id as the first argument.

insert : Decoder a -> Encoder -> Path (CollectionPath b) -> Task Error (Document a)

Insert a document into a collection.

The document will get a fresh document id.

upsert : Decoder a -> Encoder -> Path (DocumentPath b) -> Task Error (Document a)

Updates an existing document.

Creates one if not present.

patch : Decoder a -> Options.Patch.Options -> Path (DocumentPath b) -> Task Error (Document a)

Updates only specific fields.

If the fields do not exists, they will be created.

delete : Path (DocumentPath a) -> Task Error ()

Deletes a document.

Will succeed if document does not exist.

deleteExisting : Path (DocumentPath a) -> Task Error ()

Deletes a document.

Will fail if document does not exist.

Query


type alias Query a =
{ transaction : Maybe TransactionId
, document : Document a
, readTime : Time.Posix
, skippedResults : Basics.Int 
}

A record structure for query operation result

runQuery : Decoder a -> Query -> Path (QueriablePath b) -> Task Error (List (Query a))

Runs a query operation

This opeartion only accepts a path built with root or document.

Error


type Error
    = Path_ PathError
    | Http_ Http.Error
    | Response FirestoreError

An error type

This type is available in order to disregard type of errors between protocol related errors as Http_ or backend related errors as Response.


type alias FirestoreError =
{ code : Basics.Int
, message : String
, status : String 
}

Data structure for errors from Firestore


type PathError
    = InvalidPath String

An error type for invalid path

Transaction


type Transaction

Data type for Transaction


type TransactionId

Transaction ID


type alias CommitTime =
Time.Posix

A time transaction commited at

begin : Firestore -> Task Error Transaction

Starts a new transaction.

commit : Firestore -> Transaction -> Task Error CommitTime

Commits a transaction, while optionally updating and deleting documents.

Only readWrite transaction is currently supported which requires authorization that can be set via Config.withAuthorization function. Transaction in Firetore works in a pattern of "unit of work". It requires sets of updates and deletes to be commited.

model.firestore
    |> Firestore.begin
    |> Task.map
        (\transaction ->
            transaction
                |> Firestore.updateTx user1 newUser1
                |> Firestore.deleteTx user2
        )
    |> Firestore.commit
    |> Task.attempt Commited

getTx : Transaction -> Decoder a -> Path (DocumentPath b) -> Task Error (Document a)

Gets a single document in transaction

listTx : Transaction -> Decoder a -> Options.List.Options -> Path (CollectionPath b) -> Task Error (Documents a)

Lists documents in transaction

runQueryTx : Transaction -> Decoder a -> Query -> Path (QueriablePath b) -> Task Error (List (Query a))

Runs a query operation in transaction

This works as almost the same as runQuery function, but the difference is that this function accepts transaction.

updateTx : Path (DocumentPath a) -> Encoder -> Transaction -> Transaction

Adds update into the transaction

deleteTx : Path (DocumentPath a) -> Transaction -> Transaction

Adds deletion into the transaction