[matchbox "0.0.9"]
Matchbox offers more than just bindings:
Quick spin to get some basic flavour:
(require '[matchbox.core :as m])
(def root (m/connect "https://<app>.firebaseio.com"))
(m/auth-anon root)
(m/listen-children
root [:users :mike :friends]
(fn [[event-type data]] (prn data)))
(def mikes-friends (m/get-in root [:users :mike :friends]))
(m/reset! mikes-friends [{:name "Kid A"} {:name "Kid B"}])
(m/conj! mikes-friends {:name "Jean"})
(m/deref
mikes-friends
(fn [key value]
(m/reset-in! root [:users :mike :num-friends]
(count value))))
(m/unauth)
Take a look at the quick intro to for a lightning tour.
For brevity, comparing to the JS Firebase API only.
Notes:
Matchbox | Firebase.js | Differences |
---|---|---|
connect | Firebase. | Supports optional korks as second parameter |
get-in | .child | Supports symbols, keywords and sequences also (korks) |
parent | .parent | - |
deref | .once | Fixed to a "value" subscription |
deref-list | .once | Returns ordered values rather than a map. Query compatible. |
reset! | .set | Data automatically serialized in a sensible manner |
reset-with-priority! | .setWithPriority | .. |
merge! | .update | .. |
conj! | .push | .. |
swap! | .transaction | Always applied locally, supports additional arguments. |
dissoc! or remove! | .remove | - |
set-priority! | .setPriority | - |
listen-to | .on | Stored in registry for easy unsubscription |
listen-list | .on | Like deref-list for listen-to |
listen-children | .on | Listen to all child events, multiplexed. |
Additionally, there are up to three variations of most functions:
*-in
variants take an optional second parameter of korks
, to refer directly to a child.
These exist for all "ending-with-a-bang" functions, as well as deref
and deref-list
.*<
variants return a channel of results instead of taking a callback.
These exist for all functions that would take a callback.*-in<
combine decoration of (1) and (2), and exist where applicable.The last two, if they exist are defined in matchbox.async
. This is so that
Matchbox can be used without a core.async
dependency.
examples
directory.Those in the cljs
folder can be compiled from the main project via
lein cljsbuild once <example-name>
, and then run by opening the 'index.html'
found in the example directory in a browser.
There is also a stand-alone demo project, reagent-example
. This example can be
launched by executing lein run
, and opening "http://localhost:3000" in a browser.
If you'd like to use re-frame
, there is a realtime chat app showcase.
swap!
takes callback in non-standard way
Since we support passing additional arguments to an update function, we can't use an optional argument for the callback.
Our solution draws inspiration from "kwargs" style signatures:
(eg. `(my-function :has "keyword" :style "arguments")`).
Coming back to swap!
, we support :callback callback-fn
at end of arg list:
(m/swap! r f) ;; call (f <val>), no callback
(m/swap! r f b c) ;; call (f <val> b c), no callback
(m/swap! r f :callback cb) ;; call (f <val>), with callback `cb`
(m/swap! r f b c :callback cb) ;; call (f <val> b c), with callback `cb`
Note that :callback
MUST appear as the second-last argument.
JVM callbacks on side thread
Depending on your environment and config, callbacks may be triggered on another thread.
This can be confusing when debugging with prn
in callbacks, as
*out*
will not be to the REPL's writer. We provide matchbox.utils/prn
as a simple
helper to ensure output is visible.
Serialization
Data | Storage | Reads back as it writes? |
---|---|---|
{} , nameable keys | JSON | Not unless all keys are keywords (rest are coerced) |
{} , richer keys | Not supported | N/A |
[] | JSON with numeric keys | Yes |
#{} | JSON with numeric keys | No, reads back as a vector |
"string" | string | Yes |
:a/keyword | ":a/keyword" | Yes |
Number | Number | Pretty much, with nits for java.math.* types |
Record | JSON | No, reads back as vanilla map |
(def)Type | JSON | No, reads back as vanilla map |
Other | Depends on platform | Expect useless strings (JS) or serious downcasting (JVM) |
See more info here
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.
Can you improve this documentation? These fine people already did:
Chris Truter, Uday Verma, Matthew Ratzke, Jeremy Taylor, Paul Lam & The Gitter BadgerEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close