Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fbielejec/cljs-firebase-client
Clojurescript library for interacting with Firebase
https://github.com/fbielejec/cljs-firebase-client
Last synced: 16 days ago
JSON representation
Clojurescript library for interacting with Firebase
- Host: GitHub
- URL: https://github.com/fbielejec/cljs-firebase-client
- Owner: fbielejec
- Created: 2019-10-11T13:11:44.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-11-18T21:40:11.000Z (2 months ago)
- Last Synced: 2025-01-04T01:39:34.918Z (21 days ago)
- Language: Clojure
- Size: 11.7 KB
- Stars: 22
- Watchers: 5
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# cljs-firebase-client
[](https://travis-ci.org/fbielejec/cljs-firebase-client)
ClojureScript wrapper library for interacting with [Firebase](https://firebase.google.com)
This library uses [shadow-cljs](https://shadow-cljs.github.io/docs/UsersGuide.html) for JavaScript integration.
For this reason you should probably use it only if your project is also using shadow-cljs / deps.edn to resolve JS dependencies.
For rationale and some possible uses see the accompanying [blog post](https://www.blog.nodrama.io/clojurescript-firebase-library/).
## Installation
Latest released version of this library:
[](https://clojars.org/fbielejec/cljs-firebase-client)
## API Overview
Stick with the API of the javascript client [docs](https://firebase.google.com/docs/web/setup), all of the documented methods have their version in the JS library.
There are helper methods to kebab-case and keywordize the return values and responses.
Most of the functions will return a JS/Promise. The [events](#events) namespace provides re-frame events which wrap some of the API (work-in-progress).
- [firebase.core](#core)
- [init!](#init)
- [firebase.auth](#auth)
- [email-sign-in](#email-sign-in)
- [email-create-user](#email-create-user)
- [on-auth-change](#on-auth-change)
- [current-user](#current-user)
- [update-user-profile](#update-user-profile)
- [logout](#logout)
- [email-login](#email-login)
- [firebase.admin](#admin)
- [init](#init)
- [server-timestamp](#server-timestamp)
- [credential](#credential)
- [list-users](#list-users)
- [delete-user](#delete-user)
- [firebase.firestore](#firebase.firestore)
- [coll-ref](#coll-ref)
- [doc-ref](#doc-ref)
- [document-add](#document-add)
- [document-set](#document-set)
- [document->clj](#document->clj)
- [snapshot->clj](#snapshot->clj)
- [query](#query)
- [get-collection](#get-collection)
- [get-document](#get-document)
- [get-document-field-value](#get-document-field-value)
- [delete-document](#delete-document)
- [where](#where)
- [order-by](#order-by)
- [start-at](#start-at)
- [start-after](#start-after)
- [limit](#limit)
- [events.firebase](#events)
Core namespace contains only one function which initializes the Firebase client.
Initialize Firebase client. Takes a map of [config](https://firebase.google.com/docs/web/setup) values as an argument. Example:
```
(firebase/init {:apiKey "key"
:authDomain "my-1b84b.firebaseapp.com"
:databaseURL "https://my-1b84b.firebaseio.com"
:projectId "my-1b84b"
:storageBucket "my-1b84b.appspot.com"
:messagingSenderId "386365028401"})
```
### `firebase.auth`
Functions to authenticate users to your app. See [doc](https://firebase.google.com/docs/auth) for more references.
`email-sign-in [{:keys [:email :password]}]`
Example:
```
(-> (auth/email-create-user {:email "[email protected]"
:password "pass"})
(.then #(-> % .-user .-uid)))
```
`on-auth-change [{:keys [:on-change]}]`
Returns a currently logged in user.
Example:
```
(.-uid (current-user)
```
Takes a [user](#current-user) and a map of field keys:
`update-user-profile [user {:keys [:photo-url :display-name]}]`
Signs out a currently logged in [user](#current-user).
Example:
```
(logout)
```
Same as [email-sign-in](#email-sign-in) extra `:on-success` `:on-error` keys to the options map with callbacks executed after a sign-in success or failure:
`email-login [{:keys [:email :password :on-success :on-error]}]`
Admin SDK lets you interact with Firebase from privileged environments.
---
**NOTE**
This namespace will only work in a NodeJS runtime environment.
---
Create [google application credentials](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application) from a service account file:
`credential [cert]`
Initialize [Firebase Admin SDK](https://firebase.google.com/docs/admin/setup/#initialize_the_sdk). Example:
```clojure
(ns my-app
(:require [app.firebase.admin :as admin]))
(defonce service-account (js/require "./assets/my-1b84b-firebase-adminsdk-svaar-a0a51894fa.json"))
(admin/init {:databaseURL "https://my-1b84b.firebaseio.com"
:credential (admin/credential service-account)})
```
See [documentation](https://firebase.google.com/docs/reference/js/firebase.firestore.Timestamp) for more details.
```
(server-timestamp)
```
Returns a JS/Promise with a list of all users:
```
(list-users)
```
#### `delete-user`
Deletes a user, takes the user id as an argument.
Example (deletes all users):
```
(-> (list-users)
(.then #(js/Promise.all (->> (js->clj % :keywordize-keys true)
:users
(map (fn [user]
(let [uid (.-uid user)]
(delete-user uid)
uid)))))))
```
This namespace contains functions for interacting with the [Cloud Firestore](https://firebase.google.com/docs/firestore/).
Obtain a reference to a collection:
```
(coll-ref "following")
```
Obtain a reference to a document, takes a path or collection and document id as arguments:
```
(doc-ref "followers" "ml8mnGIEINP1eol2PSWSfnlen0Q2")
;; same as
(doc-ref "followers/ml8mnGIEINP1eol2PSWSfnlen0Q2")
```
Sets (creates) a document with a given id under a cpecified collection.
Creates or overwrite a single document inside a collection, returns a JS/Promise.
If the documetn does not exist it will be created, unless the merge option is specified.
Example:
```clojure
(-> (document-set {:collection "followers"
:id "VFdERNhp94PIJijeuxjJYXTLEZm2"
:document {"ml8mnGIEINP1eol2PSWSfnlen0Q2" true}}
{:merge true})
(.then #(document-set {:collection "following"
:id "ml8mnGIEINP1eol2PSWSfnlen0Q2"
:document {"VFdERNhp94PIJijeuxjJYXTLEZm2" true}}
{:merge true})))
```
Same as [document-set](#document-set) but without specifying an id, instead lets Cloud Firestore auto-generate an ID.
Returns a JS/Promise which resolves to a generated [doc-ref](#doc-ref).
Example:
```clojure
(let [sender-id "ml8mnGIEINP1eol2PSWSfnlen0Q2"
receiver-id "VFdERNhp94PIJijeuxjJYXTLEZm2"
message "Hi Bob!"
doc {:message message
:sender-id sender-id
:receiver-id receiver-id
:created-at (.getTime (js/Date.))}]
(-> (document-add {:path (string/join "/" ["messages" receiver-id sender-id])
:document doc})
(.then #(document-add {:path (string/join "/" ["messages" sender-id receiver-id])
:document doc}))))
```
Takes a document and returns a clojure representation.
`document->clj [doc]`
Takes a [query](#query) snapshot and returns a clojure representation.
`snapshot->clj [snapshot]`
Executes a query (get). Takes a document or collection ref as an argument, returns a JS/Promise resolving to a [snapshot](#snapshot) with the results.
`query [ref]`
Executes a [query](#query) on a collection, return a JS/Promise with the collection content.
`get-collection [collection]`
Executes a [query](#query) on a document, return a JS/Promise with the document content.
`get-document [collection id]`
#### `get-document-field-value`
Takes a document and a field name, returns the value.
Example:
```
(get-document-field-value (doc-ref "followers/ml8mnGIEINP1eol2PSWSfnlen0Q2") "id")
```
Deletes document from a collection. Takes a `path` or collection and document id as arguments.
```
(delete-document "followers" "ml8mnGIEINP1eol2PSWSfnlen0Q2")
;; same as
(delete-document "followers/ml8mnGIEINP1eol2PSWSfnlen0Q2")
```
Takes a collection ref, operator, key and a value, returns the same ref, but now you need can call a [query](#query) to execute the search.
This query will return a [snapshot](#snapshot->clj) of documents in the `"following"` collection where the key `"ml8mnGIEINP1eol2PSWSfnlen0Q2"` has the value `true`:
```
(-> (coll-ref "following")
(where ">=" "ml8mnGIEINP1eol2PSWSfnlen0Q2" true)
query)
```
#### `order-by`
`order-by [coll-ref field & direction]`
`start-at [coll-ref index]`
`start-after [coll-ref index]`
`limit [coll-ref n]`
This namespace contains [re-frame](https://github.com/Day8/re-frame) event wrappers around other api functions.