High-level API for ElmFire

Treat your Firebase data like a local Dict

This package provides an API layer on top of the basic ElmFire API, that treats a Firebase collection as a key-value store and makes it available basically as an Elm dictionary with corresponding operations on it.

The package consists of two modules, for reading and writing respectively:

• ElmFire.Dict

  • Mirroring a Firebase location as an Elm Dict
  • Getting a signal of all updates
  • One-time retrieval

• ElmFire.Op

  • Inserting, updating and deleting of single key-value pairs
  • Inserting and deleting lists of key-value pairs
  • Updating the whole collection via the higher-order functions map, filter and filterMap
  • Operations on the whole store can selectively be run sequentially, in parallel or as a single transaction.

General Usage Pattern

These two modules are intended to be used together.

• The state of the mirrored store will be held as a dictionary as part of the application's model.
• Operations on the store are performed by the appropriate actions of the application.

Local modifications will be reflected immediately in addition to be sent to the Firebase server and to other clients subscribed to the same Firebase location. Likewise, remote modifications will be reflected in the local mirror.

Configuration

All functionality of the package is guided by a configuration record that defines type mappings and other specifics of the Firebase collection.

type alias Config v =
  { location: ElmFire.Location
  , orderOptions: ElmFire.OrderOptions
  , encoder: v -> JD.Value
  , decoder: JD.Decoder v
  }

location specifies the Firebase and sub-path where the store is hosted.

orderOptions can be used to filter and limit the elements, that should be included in the local mirror. Use ElmFire.noOrder to access the whole collection.

The API is parameterized on the store's value type v. This can be any Elm type, as long as suitable conversion functions are provided. Note that the keys are always of type String.

encoder and decoder are the functions used to convert between the value type in Elm code and the JSON schema in the Firebase.

Example Code

We setup a simple store with values of type Int.

url = "https://myfirebase.firebaseio.com/sub/path"

config : ElmFire.Dict.Config Int
config =
  { location = ElmFire.fromUrl url
  , orderOptions = ElmFire.noOrder
  , encoder = Json.Encode.int
  , decoder = Json.Decode.int
  }

Start to mirror the store as a signal model.

mirror = ElmFire.Dict.mirror config

port initSubscription : Task ElmFire.Error (Task ElmFire.Error ())
port initSubscription = fst mirror

model : Signal (Dict String Int)
model = snd mirror

Define two operations on the store and run them. The result will be reflected in the mirror.

-- Initialize the store  (run the tasks via a port)
opInit : ElmFire.Op.Operation Int
opInit =
  ElmFire.Op.fromList
    ElmFire.Op.sequential
    [("foo",1), ("bar",2)]

-- Double each value
opMap : ElmFire.Op.Operation Int
opMap =
  ElmFire.Op.map
    ElmFire.Op.sequential
    (\key val -> val * 2)

port runOperation : Task ElmFire.Error (List ElmFire.Reference)
port runOperation =
  Task.sequence <|
    List.map (ElmFire.Op.operate config) [opInit, opMap, opMap]

The package includes the complete example code in directory example/. There is also a more detailed demonstration app in directory demo/

Examples of projects using elmfire-extra

TodoMVC

An example usage of this package is this fork of TodoMVC. It uses Firebase to store and share the todo items.

It utilizes ElmFire.Dict and ElmFire.Op in the aforementioned usage pattern.

elmfire-extra-hello-world

Raine Revere published some instructive minimal example code. Starts here.