Cortex is an immutable data store for managing deeply nested structure with React

Key features:

• supports deeply nested data
• uses immutable data, which allows fast comparison in shouldComponentUpdate
• very efficient batch updates
• simple APIs with built-in methods for working with arrays and hashes
• very lightweight (4.5kB minified and gzip)
• written in ES6

Demos

skyline (4-level nested components)

file system (arbitrarily deep structure of a single component type)

Quickstart

Initialize a cortex object

var data = {a: 100, b: [1, 2, 3]};

    var cortex = new Cortex(data, function(updatedCortex) {
      //trigger React component to update props
      myComponent.setProps({cortex: updatedCortex});
    });

Get a nested cortex object

cortex.a

    //Also works
    cortex['a']

Get a nested cortex element in an array

cortex.b[0]

Get the actual value

cortex.a.getValue()
    // ==> 100

Change data

cortex.a.set(200);
    cortex.a.getValue();
    // ==> 200

Change data from root object

cortex.set({a: 300})
    cortex.getValue()
    // ==> {a: 300}

Add callbacks

cortex.onUpdate(myCallback);

ES6 Guide

Since React 0.13.0 removed setProps for ES6 React.Component class you have to define your cortex data as state instead

class MyComponent extends React.Component {
      constructor(props) {
        super(props);

        // Assume you pass your data into props as myData
        var myCortex = new Cortex(props.myData, (updatedCortex) => {
          this.setState({myCortex: updatedCortex});
        });

        this.state = {myCortex: myCortex};
      }

      render() {
        // access cortex data from this.state.myCortex
      }
    }

Cortex 2.0 migration guide

The biggest change in v2 is immutable data. This allows us to implement shouldComponentUpdate as easy as

shouldComponentUpdate: function(nextProps, nextState) {
      return nextProps.myCortex !== this.props.myCortex;
    }

Immutability also allows us to remove getChanges and didChange methods.

BREAKING CHANGES

• `on('update', callback) is now simply onUpdate(callback)
• `off('update', callback) is removed
• insertAt and removeAt are replaced by splice, which behaves the same way as Array.prototype.splice
• add is replaced by merge
• for aesthetic reason, remove and destroy are swapped. So you would call remove(key) to remove a nested child and call destroy to remove self.

Overview

In React's world data flows in one direction from the top down. That means if you want to make a change, change it at the source and let it propagate down the chain. But what happens when a child component needs to update the data? React's official guideline is to use callback for communication between parent and child components.

However, this simply isn't sustainable even for trivially nested data. Imagine a Restaurant app in which the Restaurant has many Orders, each has many Items, each of which has many Modifiers. If you want to update a spiciness Modifier from 'hot' to 'mild' you'd have to pass the data changes several levels up. This is not only awkward but also creates unnecessary extra code in each component in the chain only for the purpose of passing data upstream.

Cortex's goal is to support arbitrarily deep data structures without requiring you to pass callbacks down the chain. Cortex achieves this by thinly wrapping your data in an object that contains the key for locating each nested piece of data as accessed from the top level. When you change the data, internally Cortex passes the new value along with its location key to update the data at the source.

Basic example

The following example has two components, Order and Item. An Order contains an array of Items, and each Item can increase its own quantity attribute.

var Item = React.createClass({
      shouldComponentUpdate: function(nextProps, nextState) {
        nextProps.item !== this.props.item;
      },
      increase: function() {
        var quantity = this.props.item.quantity.getValue();
        this.props.item.quantity.set(quantity + 1);
      },
      subTotal: function() {
        return this.props.item.quantity.getValue() * this.props.item.price.getValue();
      },
      render: function() {
        return(
          <div className="item">
            <a href="#" onClick={this.increase}>+</a>
            <span>{this.props.item.quantity.getValue()}</span>
            <span>{this.props.item.name.getValue()}</span>
            <span>${this.subTotal()}</span>
          </div>
        );
      }
    });

    var Order = React.createClass({
      shouldComponentUpdate: function(nextProps, nextState) {
        return nextProps.order !== this.props.order;
      },
      render: function() {
        var items = this.props.order.map(function(item){
          return <Item item={item} />;
        });
        return(
          <div>{items}</div>
        );
      }
    });

    var orderData = [
          {name: "Burger", quantity: 2, price: 5.0},
          {name: "Salad", quantity: 1, price: 4.50},
          {name: "Coke", quantity: 3, price: 1.50}
        ];

    //Initialize cortex with data and pass in a callback to run when data is updated.
    var orderCortex = new Cortex(orderData);

    var orderComponent = React.renderComponent(
      <Order order={orderCortex} />, document.getElementById("order")
    );

    orderCortex.on("update", function(updatedOrder) {
      orderComponent.setProps({order: updatedOrder});
    });

First we initialize cortex with:

var orderCortex = new Cortex(orderData);

Then it's passed into the Order component to render the Item components.

We set a callback to run on update event using

orderCortex.on("update", function(updatedOrder) {
      orderComponent.setProps({order: updatedOrder});
    });
    

In Item component, note that we display the quantity value with this.props.item.quantity.getValue(). This is because this.props.item.quantity only gives us the wrapper of the quantity attribute, we need to call getValue() to get the actual value.

In increase method, we use this.props.item.quantity.set(quantity + 1) to add 1 to the current quantity value.

Note that we implement shouldComponentUpdate by simply comparing the current and next props. This comparison is extremely fast since cortex returns a brand new immutable wrapper when data change.

Cortex API

Initialize:

new Cortex(data, function() {
      //trigger your React component to update
    });

Instance methods:

Cortex wrapper of array data has the following methods:

Cortex wrapper of hash data has the following methods:

CDN

cortex.2.0.0.js cortex.2.0.0.min.js

Install via Bower

bower install cortexjs

Reference the js file

<script src="/bower_components/cortexjs/build/cortex.js"></script>

Using cortex with node.js

Install via npm

npm install cortexjs

Use it:

Cortex = require("cortexjs");

    wrappedData = new Cortex({mydata: 1});
    console.log(wrappedData.mydata.getValue()); //1

    wrappedData.mydata.set(100);
    console.log(wrappedData.mydata.getValue()); //100

Building Cortex

To build Cortex:

gulp

To run test:

gulp test

To compile jsx files in examples into js files:

gulp react

Design & Optimizations

Besides providing the convenience of allowing you to update data from any level, Cortex also has several optimizations that help boost performance.

1. Deep comparison between old and new values

When you issue a set(newValue) call, no data actually changes at that point. What happens internally is the wrapper being called publishes a notification to the master cortex wrapper passing along a payload consisting of the path for locating the data and the new value (Yes, there is a pub/sub system within Cortex.) The root wrapper then performs a deep comparison between the old and new data to determine whether it should trigger the update action. If no change was made, the process just terminates without touching the data nor invoking the callbacks.

Deep comparison may sound costly but in practice when you call set(newValue) the newValue usually isn't deeply nested (if it is and the actual change is many layers deep then you should consider calling set(newValue) on the wrapper at the level that the change actually occurs.) In some situations where you have to pass in arbirarily deeply nested value the comparison work is still worth it because it can potentially save you from unnecessarily rewrapping and triggering React to update.

2. Batch rewrap and invoke callbacks once for multiple updates

When multiple updates occur at the same time, it will result in the same number of data rewrapping and callback invocations, which usually involve triggering React to update that same number of times. While React has good diffing algorithm for efficiently redrawing the DOM it would be even more efficient if React doesn't have to perform DOM comparison mutliple times. Cortex avoids triggering React by running callback only once for updates happening at the same time. This is especially useful when an array is being updated one element at a time or a deeply nested piece of data change at multiple levels.