mobservable

mobservable

Keeps views automatically in sync with state. Unobtrusively.

A Five minute, interactive introduction to Mobservable and React

API documentation - Tips & Tricks - ES5, ES6, TypeScript syntax examples - TypeScript Typings

Introduction

Mobservable is a library to create reactive state and views. Mobservable updates views automatically when the state changes, and thereby achieves inversion of control. This has major benefits for the simplicity, maintainability and performance of your code. This is the promise of Mobservable:

• Write complex applications which unmatched simple code.
• Enable unobtrusive state management: be free to use mutable objects, cyclic references, classes and real references to store state.
• Write declarative views that track their own dependencies. No subscriptions, cursors or other redundant declarations to manage.
• Build high performing React applications without Flux or Immutable data structures.
• Predictable behavior: all views are updated synchronously and atomically.

The essentials

Mobservable can be summarized in two functions that will fundamentally simplify the way you write React applications. Lets take a look at this really really simple timer application:

var timerData = {
  secondsPassed: 0
};

setInterval(function() {
  timerData.secondsPassed++;
}, 1000);

var Timer = React.createClass({
  render: function() {
    return (<span>Seconds passed: { this.props.timerData.secondsPassed } </span> )
  }
});

React.render(<Timer timerData={timerData} />, document.body);

So what will this app do? It does nothing! The timer increases every second, but the will UI never update. To fix that, we should force the UI to refresh somehow upon each interval. But that is the kind of dependency we should avoid in our code. We shouldn't have to pull data from our state to update the UI. Instead, the data structures should be in control and call the UI when it needs an update. The state should be pushed throughout our application. This is called inversion of control.

We can apply two simple functions of Mobservable to achieve this.

mobservable.makeReactive

The first function is makeReactive. It is the swiss knife of mobservable and turns any data structure and function into its reactive counterpart. Objects, arrays, functions; they can all be made reactive. Reactiveness is contagious; new data that is put in reactive data will become reactive as well. To make our timer reactive, just change the first three lines of the code:

var timerData = mobservable.makeReactive({
  secondsPassed: 0
});

mobservable.reactiveComponent

The second important function is reactiveComponent. It turns a Reactjs component into a reactive one, that responds automatically to changes in data that is used by its render method. It can be used to wrap any react component, either created by using ES6 classes or createClass. So to fix the example, just update the timer definition to:

var Timer = mobservable.reactiveComponent(React.createClass{
  /** Omitted */
}));

Its as simple as that. The Timer will now automatically update each time timerData.secondsPassed is altered. The actual interesting thing about these changes are the things that are not in the code:

• The setInterval method didn't alter. It still treats timerData as a plain JS object.
• There is no state. Timer is still a dumb component.
• There is no magic context being passed through components.
• There are no subscriptions of any kind that need to be managed.
• There is no higher order component that needs configuration; no scopes, lenses or cursors.
• There is no forced UI update in our 'controller'.
• If the Timer component would be somewhere deep in our app; only the Timer would be re-rendered. Nothing else.

All this missing code... it will scale well into large code-bases! It does not only work for plain objects, but also for arrays, functions, classes, deeply nested structures.

Getting started

Either:

• Edit a simple ToDo application online.
• npm install mobservable --save
• Clone the boilerplate repository containing the above example from: https://github.com/mweststrate/react-mobservable-boilerplate.
• Or fork this JSFiddle.

Examples

• The ports of the Notes and Kanban examples from the book "SurviveJS - Webpack and React" to mobservable.
• A simple webshop using React + mobservable or JQuery + mobservable.
• Simple timer application in JSFiddle.
• TodoMVC, based on the ReactJS TodoMVC.

Read more

• Five minute interactive introducton to Mobservable and React
• Making React reactive: the pursuit of high performing, easily maintainable React apps
• Pure rendering in the light of time and state
• Official homepage
• Advanced tips & tricks

Runtime behavior

• Reactive views always update synchronously (unless transaction is used)
• Reactive views always update atomically, intermediate values will never be visible.
• Reactive functions evaluate lazily and are not processed if they aren't observed.
• Dependency detection is based on actual values to real-time minify the amount of dependencies.
• Cycles are detected automatically.
• Exceptions during computations are propagated to consumers.

Top level api

For the full api, see the API documentation. This is an overview of most important functions available in the mobservable namespace:

makeReactive(value, options?) Turns a value into a reactive array, object, function, value or a reactive reference to a value.

reactiveComponent(reactJsComponent) Turns a ReactJS component into a reactive one, that automatically re-renders if any reactive data that it uses is changed.

extendReactive(target, properties) Extends an existing object with reactive properties.

sideEffect(function) Similar to makeReactive(function). Exception the created reactive function will not be lazy, so that it is executed even when it has no observers on its own. Useful to bridge reactive code to imperative code.

FAQ

Is mobservable a framework?

Mobservabe is not a framework. It does not tell you how to structure your code, where to store state or how to process events. Yet it might free you from frameworks that poses all kinds of restrictions on your code in the name of performance.

Can I combine flux with mobservable?

Flux implementations that do not work on the assumption that the data in their stores is immutable should work well with mobservable. However, the need for flux is less when using mobservable. Mobservable already optimizes rendering and since it works with most kinds of data, including cycles and classes. So other programming paradigms like classic MVC are now can be easily applied in applications that combine ReactJS with mobservable.

Can I use mobservable together with framework X?

Probably. Mobservable is framework agnostic and can be applied in any JS environment. It just ships with a small function to transform Reactjs components into reactive view functions for convenience. Mobservable works just as well server side, and is already combined with JQuery (see this Fiddle) and Deku.

Can I record states and re-hydrate them?

Yes, some examples are coming shortly!

Can you tell me how it works?

Sure, join the reactiflux channel our checkout dnode.ts. Or, submit an issue to motivate me to make some nice drawings :).