redux-primus

An opinionated connector between primus and redux.

Based on https://github.com/itaylor/redux-socket.io

Basically just changed emit -> send

Due to the way primus works, it requires you to source the primus client generated by the primus server. By bundling in a static version in your SPA or getting it from the server at runtime.

Also for now requires you to use https://github.com/cayasso/primus-emitter

Philosophy

primus client->server messages should should be sent by dispatching actions to redux's store, where the action is the payload.

primus server->client messages should be dispatched as actions when received.

How to use

Installation

npm install --save redux-primus

Example usage

This will create a middleware that sends actions to the server when the action type starts with "server/". When the primus spark receives a message of type 'action', it will dispatch the action to the store.

The result of running this code from the client is a request to the server and a response from the server, both of which go through the redux store's dispatch method.

Client side:

import { createStore, applyMiddleware } from 'redux';
import createPrimusMiddleware from 'redux-primus';
import primus from 'client';
let spark = primus('http://localhost:3000');
let primusMiddleware = createPrimusMiddleware(spark, "server/");
function reducer(state = {}, action){
  switch(action.type){
    case 'message':
      return Object.assign({}, {message:action.data});
    default:
      return state;
  }
}
let store = applyMiddleware(primusMiddleware)(createStore)(reducer);
store.subscribe(()=>{
  console.log('new client state', store.getState());
});
store.dispatch({type:'server/hello', data:'Hello!'});

Allowed criteria for action matching

When you create this middleware, you can configure how it detects that a given action should be sent to primus. This is done with the second parameter to createPrimusMiddleware.

You can pass either a prefix string that will be matched against the action.type:

let primusMiddleware = createPrimusMiddleware(spark, 'server/');

An array of strings that will will be used as allowed prefixes:

let primusMiddleware = createPrimusMiddleware(spark, [ 'post/', 'get/' ]);

Or a function that returns a truthy value if the action should be sent to primus:

let primusMiddleware = createPrimusMiddleware(spark, (type, action) => action.io);

Advanced usage

The default behavior is an "optimistic" update mode, where if an action matches the criteria you provided when you created the primus middleware, the middleware calls spark.send('action', action) and then passes the action to the next middleware in the chain.

If you want to change this behavior, you can provide your own execute function that allows you to decide what to do with the action that matched your criteria.

You do this by providing a function (action, emit, next, dispatch) as the execute property of the third parameter of createPrimusMiddleware

Example execute functions:

This is equivalent to the default execute function, so this is what will happen if you don't override it. Use something like this if you want optimistic updates of your state, where the action you dispatch goes both to the server and to the redux reducers.

import createPrimusMiddleware from 'redux-primus';
function optimisticExecute(action, emit, next, dispatch) {
  emit('action', action);
  next(action);
}
let primusMiddleware = createPrimusMiddleware(spark, "server/", { execute: optimisticExecute });

Here's a function that would make the middleware swallow all the actions that matched the criteria and not allow them to continue down the middleware chain to the reducers. This is easily used to make "pessimistic" updates of your state, by having the server respond by sending back an action type of the same type it was sent.

import createPrimusMiddleware from 'redux-primus';
function pessimisticExecute(action, emit, next, dispatch) {
  emit('action', action);
}
let primusMiddleware = createPrimusMiddleware(spark, "server/", { execute: pessimisticExecute });

Here's a function that would make the middleware dispatch an alternate action that could be used in a scenario where you want the optimistic updates to be very explicit. Here you would have actions of type server/<actionName> sent to the server, and also have another action optimistic/<actionName> dispatched as well with the same content.

import createPrimusMiddleware from 'redux-primus';
function optimisticExecute(action, emit, next, dispatch) {
  emit('action', action);
  const optimisticAction = {
    ...action,
    type: 'optimistic/' action.type.split('/')[1];
  }
  dispatch(optimisticAction);
}
let primusMiddleware = createPrimusMiddleware(spark, "server/", { execute: optimisticExecute });