Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thomasweiser/elmfire-extra

High-level API for ElmFire
https://github.com/thomasweiser/elmfire-extra

elm elmfire firebase

Last synced: 25 days ago
JSON representation

High-level API for ElmFire

Awesome Lists containing this project

README 

        
# 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](http://package.elm-lang.org/packages/ThomasWeiser/elmfire/latest) 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.



```elm

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`.

```elm

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`.

```elm

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.

```elm

-- 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](https://github.com/ThomasWeiser/todomvc-elmfire). It uses Firebase to store and share the todo items.



It utilizes `ElmFire.Dict` and `ElmFire.Op` in the aforementioned [usage pattern](#general-usage-pattern).



### elmfire-extra-hello-world



Raine Revere published some instructive minimal example code. Starts [here](https://github.com/metaraine/elmfire-extra-hello-world).