@synchemy/core v1.0.9

Synchemy

Install

npm install @synchemy/core --save

Install synchemy useStore hook to use with react

npm install @synchemy/use-store --save

Package versions

Name	Latest Version
@synchemy/core

Description

Synchemy is a state management library that keeps the client side store automatically in sync with the server using websockets.

On the server side, this library uses an evented approach to receive and send back messages to the client. Any messages sent back to the client will update the store, unless explicitly told not to. This eliminates the need for a REST api and makes it quite easy to keep data in sync with the client.

On the client side, you can register actions that will automatically generate loading flags for each action. Any time you call an action, a loading flag is automatically created. It is set to true at the beginning of the action and set to false at the end of the action. If used with react, you can use the useStore hook to subscribe to any store or loading flag changes. Actions also come with a debounce or throttle option in case you need to debounce or throttle your actions.

Here is the simplest client side and server side setup you can have:

Client

const { SynchemyClient } = require('@synchemy/core')

const synchemy = new SynchemyClient({
  host: 'ws://localhost:4000'
})

synchemy.updateStore({ todos: [] })
synchemy.registerAction('GET_TODOS', async () => {
  await synchemy.send({ type: 'GET_TODOS' })
})

synchemy.subscribe((state, loaders) => {
  return {
    todos: state.todos,
    todosLoading: loaders.getTodos.loading
  }
}, store => {
  console.log('NEW STORE: ', store)
}) // you can add a shouldUpdate function as a 3rd param.

synchemy.actions.getTodos()

Server

const { SynchemyServer } = require('@synchemy/core')

const synchemy = new SynchemyServer({ port: 4000 });
synchemy.onMessage(({ message }) => {
  if (message.type === 'GET_TODOS') {
    return { todos: [{ name: 'first todo' }] }
  }

  return message;
});

Now let's take a look at the setup if using React.

SynchemyClient setup with React

First, let's create the synchemy instance and keep it in a separate file for easy imports.

// synchemy.js
import { SynchemyClient } from '@synchemy/core';

const synchemy = new SynchemyClient({
  host: 'ws://localhost:3000'
})

export default synchemy

Next, you can initialize the store with some initial data and register your actions.

// index.js
import React from "react";
import ReactDOM from "react-dom";
import Home from "./pages/home";
import synchemy from './synchemy';
import registerActions from './actions';

synchemy.updateStore({ counter: 0, todos: [] })
registerActions();
ReactDOM.render(<Home />, document.getElementById("app"));

Here we register our actions. In this specific case, we register a GET_TODOS action. The action can get called by invoking synchemy.actions.getTodos(). This will automatically create a synchemy.asyncActions.getTodos.loading flag that will be set to true in the beginning of the action and set to false at the end of the action.

// actions.js
import synchemy from './synchemy';

const registerActions = () => {
  synchemy.registerAction('GET_TODOS', async () => {
    // sent messages receive a response from the server.
    // The store will be automatically updated with props from the 
    // response, unless you pass in { updateStore: false } as an option.
    // ex: const response = await synchemy.send({ type: 'GET_TODOS' }, { updateStore: false });
    const response = await synchemy.send({ type: 'GET_TODOS' });
  });
};

export default registerActions;

Debounce or throttle options can be set this way.

  synchemy.registerAction('GET_TODOS', async () => {
    const response = await synchemy.send({ type: 'GET_TODOS' });
  }, { debounce: 500 });

Alternatively, you can also register your actions directly in the SynchemyClient constructor.

const synchemy = new SynchemyClient({
  host: 'ws://localhost:3000',
  actions: {
    getTodos: {
      name: 'GET_TODOS',
      action: async () => {},
      options: { throttle: 500 } // options are optional
    }
  }
})

useStore hook setup with React

You must first call useStore with the synchemy instance. You'll then get back a function which you can call with a callback invoked anytime there is a store change or a loading flag change. Your component will rerender only if the changes are in any of the properties that you return from the callback.

// app.js
import React, { useEffect } from 'react';
import synchemy from './synchemy';
import useStore from '@synchemy/use-store'

const App = () => {
  const store = useStore(synchemy)((state, loaders) => {
    return {
      todos: state.todos,
      getTodosLoading: loaders.getTodos.loading
    }
  });

  useEffect(() => {
    synchemy.actions.getTodos()
  }, []);

  return <div>
    TODOS
    {store.getTodosLoading &&
      <div>loading...</div>
    }
    {!store.getTodosLoading &&
      <div>
        {store.todos.map(todo => {
          return <Todo key={todo.id} {...todo} />
        })}
      </div>
    }
  </div>;
}

export default App;

Rerenders are based on the properties that you return from the useStore callback. However, only a shallow comparison is made between the previous state and the next state to determine whether a change has occured. If you want more customization on whether an update should occur, you can provide a shouldUpdate function.

const store = useStore(synchemy)((state, loaders) => {
  return {
    todos: state.todos,
  }
}, (prevState, nextState) => {
  if (prevState.todos.length !== nextState.todos.length) {
    return true
  }

  return false
});

SynchemyServer setup with Node and Express

Whenever you send an event from the client side using synchemy.send({ type: 'GET_TODOS' }), the onMessage callback will get called. Whatever you return will then automatically update your store on the client side, unless you send the event using synchemy.send({ type: 'GET_TODOS' }, { updateStore: false }).

const express = require('express');
const server = require('http').createServer();
const { SynchemyServer } = require('@synchemy/core');

var app = express();

const synchemy = new SynchemyServer({ app, server });
synchemy.onMessage(async (({ message, socketId }) => {
  // The socketId can be tracked to send messages to specific clients. All socket ids
  // are accessible on synchemy.sockets

  if (message.type === 'GET_TODOS') {
    // to whatever you need to do to fetch todos
    const todos = await getTodos()
    return { todos }
  }

  return message;
});

You can send messages to all clients...

synchemy.sendAll(message)

...or to an array of specific clients.

synchemy.send(socketIds, message)

If you don't want the client side store to update itself automatically when you send a message to the client using synchemy.sendAll or synchemy.send, you can set a callback on the client side to react to messages from the server and perhaps update the store yourself.

// this is on the client side
synchemy.onMessage(message => {
  // do something
})

Finally, if you need to do something on socket connection or socket disconnection, you can setup these callbacks.

  synchemy.onSocketConnection(callback)
  synchemy.onSocketDisconnection(callback)

synchemyClient methods

synchemyClient properties

synchemyServer methods

synchemyServer properties