syncmachine-sdk v0.1.3

What is Sync Machine?

Sync Machine is a service that handles data synchronization for your React application.

It's based on a similar programming model to Redux, where changes to your application's state is described through events that change the state.

Concepts

Sync Machine has three concepts:

Application

Creating an application gives you an API key that you can use to connect your React app to Sync Machine.

Entity

An entity is any object in your application that you want to synchronize.

Are you creating a To-do list app? Then you'll probably have List entities with a bunch of items.

Update

Any time an entity changes, your application posts an update to Sync Machine.

An update can be any JSON value.

Getting started

There's three steps to add Sync Machine to your React application.

Step 1: Add syncmachine-sdk to your package.json

Step 2: Create an Application to get an API key

Go to https://syncmachine.herokuapp.com and create an account, then create an Application to generate an API key.

Save this API key for the next step.

Step 3: Wrap your app in a SyncMachineSocketProvider

Somewhere at the top level of your React application, add this:

import {SyncMachineSocketProvider} from 'syncmachine-sdk';

// ...

    return <SyncMachineSocketProvider apiKey={'API KEY GOES HERE'}>
        Your app goes here
    </SyncMachineSocketProvider>;

This will make the SDK connect to Sync Machine and create a connection to your Application.

It provides this connection, in the React context, to the entity hooks we'll make in the next step.

Step 4: Add a Sync Machine entity hook

In the component that renders your entity, use the useSyncMachineEntity hook to connect to a Sync Machine entity.

I'm going to assume here that we're going to make a To-do list application, with a List entity. Go ahead and substitute whatever entity type works for your app.

First, create an entity definition that looks like this:

const listEntity = {
    kind: 'List',
    initialState: () => (
      { name: "Unnamed list", items: [] }
    ),
    applyUpdate: (entity, update) => {
      console.log("Applying update: ", update);
      // TODO: apply the update and return a new list 
      return entity;
    }
};

There's three parts to an entity definition:

• kind: This names the kind of entity.
• initialState: This gives the structure of the entity before any updates have been applied to it.
• applyUpdate: This function should apply the update to the entity and return the new state of the entity.

  • If you're familiar with Redux, this is like a 'reducer'.

Next, use the hook to get the state of the entity. For now we'll just render the state as JSON:

const List = ({id}) => {
    const [list, entity] = useSyncMachineEntity({
        ...listEntity, id,
    });
    
    return <div>{JSON.stringify(list)}</div>;
}

Step 4: Write the applyUpdate function

Finally, actually write the applyUpdate function.

TODO

Step 5: Post updates

Whenever the user makes a change to the entity, post an update to the entity.

For example, if they add an item to the List you might do this:

    entity.postUpdate({
      type: 'insert-item',
      data: {
        id: uuid(),
        title: 'New item title',
        completed: false
      }
    });

This update will get added to the entity's update stream and broadcast to all clients. They'll apply it with their applyState function and render the new state.