cerebral-provider-firebase
Firebase provider for Cerebral
Install
This project is still in alpha. To test alpha version check instructions in monorepo.
Setup
const controller =
Important notes
-
The Cerebral firebase provider uses dot notation to keep consistency with Cerebral itself
-
All factories supports template tags, allowing you to dynamically create paths and points to values
Set data
set
Write data to this database location. This will overwrite any data at this location and all child locations. Passing null for the new value is equivalent to calling remove(); all data at this location or any child location will be deleted.
action
{ return firebase }
factory
success: error:
update
As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location).
action
{ return firebase }
factory
success: error:
push
Generates a new child location using a unique key and returns its reference from the action. An example being {key: "-KWKImT_t3SLmkJ4s3-w"}
.
action
{ return firebase }
factory
success: error:
remove
Remove the data at this database location.
action
{ return firebase }
factory
success: error:
transaction
Atomically modifies the data at the provided location.
Unlike a normal set(), which just overwrites the data regardless of its previous value, transaction() is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time.
To accomplish this, you pass transaction() an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function.
action
{ { if currentData === null return foo: 'bar' return // Abort the transaction. } return firebase }
factory
{ if currentData === null return foo: 'bar' return // Abort the transaction.} success: error:
Note: Modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and transaction() to update the same data.
Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs .read access in addition to .write access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it.
Retrieve data
Value
action
{ return firebasevalue'someKey.foo' ;}
The result will be available as { key: 'foo', value: 'bar' }
. Or { error: 'error message'}
.
factory
success: error:
Retrieve data with updates
When you also want to know when your queried data updates you have the following methods:
onValue
action
{ firebase;}
This will NOT immediately grab the value and trigger the signal passed, the first event is discarded for more predictable behaviour. To grab existing value, just use value
.
To stop listening for updates to the value:
{ firebase;}
factory
onChildAdded
action
{ firebase;}
This will immediately grab and trigger the signal posts.postAdded
for every post grabbed. Note this is just registering a listener, not returning a value from the action. The signal is triggered with the payload: { key: 'someKey', value: {} }
.
To stop listening for updates to the posts:
{ firebase;}
factory
onChildRemoved
action
{ firebase;}
This will trigger the signal posts.postRemoved
whenever a post is removed from the selection. The signal is triggered with the payload: { key: 'someKey' }
.
To stop listening:
{ firebase;}
factory
onChildChanged
action
{ firebase;}
This will trigger the signal posts.postChanged
whenever a post is changed in the selection. The signal is triggered with the payload: { key: 'someKey', value: {} }
.
To stop listening:
{ firebase;}
factory
Tasks
If you are using the firebase-queue and need to create tasks, you can do that with:
action
{ return firebase ;}
This will add a task at queue/tasks
. There is no output from a resolved task, it just resolves when the action has been processed.
factory
success: error:
Authentication
Get user
Will resolve to {user: {}}
if user exists. If user was redirected from Facebook/Google etc. as part of first sign in, this method will handle the confirmed registration of the user.
action
{ return firebase ;}
factory
success: error:
Anonymous login
This login will method will resolve to existing anonymous or create a new one for you. Resolves to {user: {}}
.
action
{ return firebase ;}
factory
success: error:
Create user with email and password
Register a new user with email and password. Resolves to {user: {}}
.
action
{ const email = state const password = state return firebase ;}
factory
success: error:
Sign in user with email and password
Sign in a user with email and password. Resolves to {user: {}}
.
action
{ const email = state const password = state return firebase ;}
factory
success: error:
Sign in with Facebook, Google or GitHub
Sign in a user with Facebook. Resolves to {user: {}}
, or redirects.
action
{ return firebase ;}
factory
success: error:
Similar you can sign in with Google or GitHub.
Just use signInWithGoogle
or signInWithGithub
instead of signInWithFacebook
.
Link with Facebook, Google or GitHub
Link an anonymous account with Facebook. Resolves to {user: {}}
, or redirects.
action
{ return firebase ;}
factory
success: error:
Similar you can sign in with Google or GitHub.
Just use linkWithGoogle
or linkWithGithub
instead of linkWithFacebook
.
Sign out
Sign out user. getUser will now not resolve a user anymore.
action
{ return firebase ;}
factory
success: error:
Send reset password email
action
{ return firebase ;}
factory
success: error:
On disconnect
setOnDisconnect
Sets a value when Firebase detects user has disconnected.
action
{ firebase}
factory
cancelOnDisconnect
Cancel setting a value when Firebase detects disconnect.
action
{ firebase}
factory
File Storage
put
Upload a new file at the given location. Please note that the file is not stored inside the realtime database but into Google Cloud Storage (please consult filrebase documentation). This means that you need to take care of storage security as well.
The options expect a progress field that can be either a signal (that will be called with progress
, totalBytes
and bytesTransferred
) or a state path to directly set progress
value.
Note that put
expects a folder as first argument and will use the name of the provided file. If you want to control the filename, add this in the options. In this case, make sure to respect file type and extension...
On success, props
contains an url
and the filename
.
// we expect props.file to contain a file provided by// a user in an <input type='file' /> success: error:
delete
Use delete
to remove an uploaded file. Specify the containing folder and filename.
firebase success: error: