firecloud v0.0.15

Fire Cloud

This package helps you sync your user data across multiple devices using firebase's firestore.

Installation

Usage

There are 2 cases you need to handle: 1. Sync user data from device to the cloud 2. Sync user data from the cloud to device

We will use a Todo List app as example

1. Device to Cloud

When syncing user data from device to cloud, there are 2 scenarios:

• A. Optimal scenario, user makes a change, it's synced to the cloud
• B. Failure scenario, user makes a change, it fails to sync (no internet, database is down,...)

A. Handle changes

a. User adds new todo

const newTodo = { id: 'todo1', title: 'Wash dishes', done: false };
FireCloud.addToCollection('todos', newTodo.id, newTodo);

b. User marks todo as done

FireCloud.updateInCollection('todos', todo.id, {done: true});

c. User selects dark theme

FireCloud.set('theme', 'dark');

d. Remove theme

FireCloud.remove('theme');

e. User removes todo

FireCloud.removeFromCollection('todos', todo.id);

B. Handle fail-to-sync changes

It might happens that when the above functions are called, the users don't have internet, so the changes are not synced to the cloud.

In that case, those changes are saved in your app, in the storage you provided.

So when user has internet again, you can call a function to sync those changes as simple as:

FireCloud.syncOfflineChangesToCloud();

This method will:

• Read the changes from the Offline Storage's unsynced list, and for each change:
  • If it's newer than the one on the cloud
    • Override the cloud's version
    • Remove the change from the Offline Storage's unsynced list
    • Add the change to the Offline Storage's synced list
  • Otherwise it does nothing

So note that, this method does not sync cloud's change with local change even when it detect a newer change on the cloud.

We recommend to call this method on app launch or on app becomes active

C. Listen to redux's actions

We also provide a set of methods for you to handle changes easily with redux

Add the middleware:

const fireCloudMiddleware = FireCloud.createMiddleware();
const middlewares = [fireCloudMiddleware, /*... other middlewares*/];
const enhancers = [applyMiddleware(...middlewares), /*... other enhancers*/];

export const store = createStore(rootReducer, compose(...enhancers));

Listen to action:

FireCloud.addActionListener('ADD_TODO', (store, action) => {
    const newTodo = action.payload.todo;
    FireCloud.addToCollection('todos', newTodo.id, newTodo);
});

FireCloud.addActionListener('CHANGE_THEME', (store, action) => {
    const newTheme = action.payload.theme;
    FireCloud.set('theme', newTheme);
});

Listen to all actions:

FireCloud.addActionListener('*', (store, action) => {
    switch (action.type) {
        case 'CHECK_TODO':
            const newTodo = action.payload.todo;
            FireCloud.updateInCollection('todos', action.payload.todo.id, {done: true});
            break;
        case 'REMOVE_TODO':
            FireCloud.removeFromCollection('todos', action.payload.todo.id);
            break;
    }
})

Remove listener:

FireCloud.removeActionListener('ADD_TODO');
FireCloud.removeActionListener('*');

2. Cloud to Device

There are 2 types of syncing from cloud to device:

• A. Passively using a listener, when there is a new change on the cloud, a callback in your app is called, you apply the change to your app
• B. Actively on app launch, on user pressing on 'Sync', on user pulling down,... You call a function to get the changes, then apply them

A. Passive syncing

Add a global listener

FireCloud.addCloudListener('*', (cloudWatcher, cloudData) => {
    if (cloudWatcher.theme) {
        dispatch({type: 'CHANGE_THEME', payload: {theme: cloudData.theme}});
        FireCloud.synced('theme', cloudWatcher.theme);
    }
    if (cloudWatcher.todos) {
        for (const todoID in cloudWatcher.todos) {
            const todoChange = cloudWatcher.todos[todoID];
            if (todoChange.type === 'removed') {
                dispatch({type: 'REMOVE_TODO', payload: todoID});
            } else if (todoChange.type === 'modified') {
                dispatch({type: 'UPDATE_TODO', payload: {id: todoID, todo: cloudData.todos[todoID]}});
            } else if (todoChange.type === 'added') {
                dispatch({type: 'ADD_TODO', payload: {todo: cloudData.todos[todoID]}});
            }
            FireCloud.synced(`todos.${todoID}`, todoChange);
        }
    }
});

( Path listener might be supported in the future )

B. Active syncing

FireCloud.fetchCloudChanges((cloudWatcher, cloudData) => {
    // Same as above
})