Experimental library for managing React app state using Proxys

Works only on browsers that support Javascript Proxys

Table of contents

• Getting stated
  • Install
  • Examples
    • eventHandlers
    • createProvider
    • mapContextToProps
• Api description
  • Context Provider
    • Subscribe
    • Get State
  • Map context state to props
  • Context eventhandlers
  • Eventhandler proxy nodes
    • State variable
    • Updating state from eventhandlers
      • clear
      • assign
      • remove
      • toggle
• More
  • Application flow
  • Caveats

Getting Started

Install

npm install react-proxy-state or yarn add react-proxy-state

Examples

eventHandler functions

Four functions: (clear, assign, remove, toggle) + state

import uuid from 'uuid/v4';

export const addTodo = (description) => ({todos}) => {
    const id = uuid();
    todos.assign({[id]: {id, description, done: false}});
};
export const toggleTodo = (id) => ({todos}) => todos[id].done.toggle();

export const removeTodo = (id) => ({todos}) => todos.remove(id);

export const removeAllTodos = () => ({todos}) => todos.clear({});

export const logTodosState= () => ({todos}) => console.log(todos.state)

createProvider

import React from 'react';
import {createProvider} from 'react-proxy-state';
import ReactDOM from 'react-dom';
import TodosApp from './components/TodosApp';
import * as todoEventHandlers from './eventHandlers/todos';

const initialState = {
    todos: {a: {id: 'a', description: 'Do Homework', done: false}}
};

const ContextProvider = createProvider(initialState, {...todoEventHandlers});

const Root = () => (
    <ContextProvider>
        <TodosApp/>
    </ContextProvider>
);

ReactDOM.render(<Root/>, document.getElementById('app'));

mapContextToProps

All eventHandlers are accessable from component context

import React, {Component} from 'react';
import {func} from 'prop-types';
import {mapContextToProps} from 'react-proxy-state';

class TodosApp extends Component {

    static contextTypes = {
        addTodo: func,
        toggleTodo: func,
        removeTodo: func,
        removeAllTodos: func,
    };

    state = {input: ''};

    render() {
        const {state: {input}, props: {todos}, context: {addTodo, toggleTodo, removeTodo, removeAllTodos}} = this;
        return (
            <div>
                {Object.values(todos).map(todo => (
                    <div key={todo.id}>
                        <p>{todo.description}</p>
                        <input type='checkbox' checked={todo.done} onClick={() => toggleTodo(todo.id)}/>
                        <button onClick={() => removeTodo(todo.id)}>remove</button>
                    </div>
                ))}
                <input value={input} onChange={e => this.setState({input: e.target.value})}/>
                <button onClick={() => addTodo(input)}>add</button>
                <button onClick={removeAllTodos}>remove all</button>
            </div>
        );
    }
}

export default mapContextToProps(({todos}) => ({todos}))(TodosApp);

import React from 'react';
import {func} from 'prop-types';

const TodoItem = ({todo}, {toggleTodo, removeTodo}) => (
    <div>
        <p>{todo.description}</p>
        <input type='checkbox' checked={todo.done} onClick={() => toggleTodo(todo.id)}/>
        <button onClick={() => removeTodo(todo.id)}>remove</button>
    </div>
);

TodoItem.contextTypes = {
    toggleTodo: func,
    removeTodo: func,
};

export default TodoItem;

Api Description

ContextProvider

Context state is served by ContextProvider-component. ContextProvider-component is created by createProvider function, that takes the initialState as first argument and eventHandlers as second argument. Both initialState and eventHandlers should be objects.

import {createProvider} from 'react-proxy-state'
...

const ContextProvider = createProvider(initialState, eventHandlers);

const Root = () => (
    <ContextProvider>
        <App/>
    </ContextProvider>
);

Read more about ContextProviders eventHandlers in section Context eventhandlers

By default ContextProvider offers subscribe and getState context functions, to all of its contextual child components.

Subscribe

subscribe takes a callback function as argument, and it return a function for cancelling the subscription. Callback function provided as the argument will be called everytime context state changes.

Get State

getState returns the current context state

Though context state can be manually be subscribed from context, Components should not access it directly. Read more about how to access context state from the next section about mapContextToProps

Map Context State To Props

Components using context state, should be defined by using mapContextToProps. mapContextToProps helps creating a higher-order Connected-component that wraps the actual component. mapContextToProps subscribes the context state, on behave of the actual component. Every time the context state changes, Connector passes the context state as properties to the actual component.

import {mapContextToProps} from 'react-proxy-state';

const Todo = ({description, done}) => (
    <div>
      <p>{description}</p>
      <p>{done ? 'Done' : 'Not done'}</p>
    </div>
)

const selector = (contextState, ownProps) => {
  const todo = contextState.todos[ownProps.todoId];
  return todo;
}
const createConnected = mapContextToProps(selector); 
export default createConnected(Todo);

mapContextToProps is a higher order function that takes a state selector as parameter. *mapContextToProps returns a createConnected function that takes the actual component as parameter.

selector is a function that takes contexts state and component own properties as parameters.

Everytime* Components properties or context state changes, this selector functions is re-run, and what ever it returns, gets passed as property by Connector to the component passed to createConnected

(if the output changes compared to the previous output)*.

Context eventhandlers

Event handlers are functions that are responsible for updating the context state. These function must be passed to createProvider as second argument durin initialization. ContextProvider server these eventHandlers to all of it's children, and components can access these eventHandlers throught context api.

const doSomething = () => proxy => {...};
const doSomethingElse = (parameter) => proxy => {...}
const eventHandlers = {doSomething, doSomethingElse}
const ContextProvider = createProvider(initialState, eventHandlers);

Eventhandlers must be defined as higher order functions. When ever a Component invokes these eventHandlers, it's result is invoked with a context state proxy as 1st argument.

ContextProviders simply transforms eventHandlers, into a reqular function, before they are server to components:

const before = (...params) => proxy => {...};
const after = (...params) => before(...param)(proxy);

For a component to be able to access eventhandlers server by ContextProvider, the component has to announce which context variables it is going to be using, by defining the components contextTypes.

import {func} from 'prop-types';
...
const Todo = ({id, description, done}, {setTodoDone}) => (
    <div>
      <p>{description}</p>
      <p onClick={() => setTodoDone(id, !done)}>{done ? 'Done' : 'Not done'}</p>
    </div>
)
Todo.contextTypes = {
  setTodoDone: func
}
const selector = ...
export default mapContextToProps(selector)(Todos);

Eventhandler proxy nodes

Every eventhanlers output (the handle function) gets a context state Proxy as the first parameter.

const myEventHandler () => proxy => { ... };

This Proxy is a root node in a shadow datastructure of the actual state. This node acts as an interface for making changes to the state, while keeping the states datastructure immutable. A single location in the shadow state is called a node.

The benefit of updating the state by using eventHandler nodes, is that all the update actions are mirrored back to the actual state, and they are applied by using pathcopying. As a result, the context state stays allways immutable.

State variable

Every node represents a particular location of the state. That state can be read by accessing nodes state variable

const logTodoStatus = (id) => (proxy) => {
    const status = proxy.todos[id].done.state;
    console.log(status); // --> true or false
}

state variable is a getter, so when accessed it always gets re-evaluated.

You should never be directly to changed or mutate nodes state property.

Updating state

There is four methods that are recommended to be used when ever the underlying state should be updated.

clear

Clear acts on behave of the assigment operation.

assign

Use assign when ever you would use Object.assign

remove

Use remove when ever you would delete values

Toggle

Toggle simply negates the current substate

More

Application flow

Caveats

1. Eventhandler nodes are not directly comparable

const eHandler = () => proxy => {
   proxy.assign({a:1, b:1});
   proxy.a === proxy.b; // false
}

2. Arrays might behave unpredictably and array update performance might be poor

3. Avoid performing any iteration on nodes

4. Keep context state as plain and normalized as possible.

• Use only strings or numbers as keys
• Just plain objects. No Class instances, or otherwise modified objects
• Serializable datastructures. No circular references
• Avoid using arrays, when ever the content of that array might change during the applications lifetime.

5. undefined values in state are considered as non-existing. To avoid errors use assign instead of clear when ever possible.