microcosm

A variant of Flux with central, isolated state.

Microcosm makes it easier to control and modify state in a pure, centralized way. It uses stateless, singleton Stores and Actions, keeping all data encapsulated in one place. This design seeks to achieve a reasonable trade off between the simplicity of singletons and the privacy of class instances.

For a deeper dive, check out the docs or continue below.

---

---

Overview

Within the context of the Flux model, Microcosm treats actions and stores as singletons, however they do not contain any state.

Actions are called within the context of a particular instance of Microcosm:

  let addPlanet = function(params) {
    return params
  }

  app.push(addPlanet, params)

Stores hold no state. Stores are collections of functions that transform old data into new data, with a hook that registers them with the Microcosm.

let Planets = {
  register() {
    return {
      [addPlanet] : this.add
    }
  },
  add(planets, props) {
    return planets.concat(props)
  }
}

let app = new Microcosm()

// All state is contained in `app`, but transformed with `Planets`
app.addStore(Planets, 'planets')

From there, an app's state can be sent down your React component tree:

React.render(<SolarSystem app={ app } planets={ app.get('planets') } />, document.body)

Opinions

1. Action CONSTANTS are automatically generated by assigning each Action function a unique toString signature under the hood.
2. Actions dispatch parameters by returning a value or a promise (only dispatching when it is resolved)
3. Actions handle all asynchronous operations. Stores are synchronous.
4. Stores do not contain data, they transform it.

What is it trying to solve?

1. State isolation. Requests to render applications server-side should be as stateless as possible. Client-side libraries (such as Colonel Kurtz) need easy containment from other instances on the page.
2. Singletons are simple, but make it easy to accidentally share state. Microcosm keeps data in one place, operating on it statelessly in other entities.
3. Easy extension of core API and layering of features out of the framework's scope.

Tutorials

Hello, Microcosm is a great place to start. With that background, Design may help to provide an additional high level overview of how things work. Beyond that, check out the example apps.

Examples

Examples can be found in the ./examples directory. To run these examples:

npm install
npm start

This will run webpack-dev-server at http://localhost:8080. From there, examples can be viewed by navigating to their associated path, such as http://localhost:8080/simple-svg.

Documentation

There is documentation here. This includes high level overviews of framework architecture, guides, and API documentation for the individual components of Microcosm.

Inspiration

• Worlds
• Om
• Elm Language
• Flummox
• But the world is mutable