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 pure, singleton Stores and Actions, keeping all state encapsulated in one place. This design seeks to achieve a reasonable trade off between the simplicity of singletons and the privacy of class instances.

---

---

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 Action = function(params) {
    return params
  }

  app.push(Action, 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 Store = {
  register() {
    return {
      [Action] : this.add
    }
  },
  add(state, params) {
    return state.concat(params)
  }
}

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 app.

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

Changelog

8.0.0

Noticeable changes

• Stores now contain the logic for how it should receive an action. logic is contained under send.
• Stores now contain the logic to determine what method should resolve an action sent to it. This is defined in register
• Microcosm::deserialize will now only operate on the keys provided by the seed object. This means that data passed into replace will only blow way keys provided in the data object.
• The signaling logic for dispatching actions will throw an error if the action provided is not a function
• Internalized tag, it will now lazy evaluate as actions are fired
• Upgraded Foliage, Microcosm now contains subscribe, unsubscribe, and publish aliases for listen, ignore, and publish

Breaking Changes

• Remove all uses of the tag module.

Changes to Stores

Before this release, stores would listen to actions using the stringified value of their functions:

var MyStore = {
  [Action.add](state, params) {}
}

This was terse, however required actions to be tagged with a special helper method. It also required any module that needed access to a Store's method to also know what actions it implemented.

To address these concerns, Stores now communicate with a Microcosm using the register method:

var MyStore = {
  register() {
    return {
      [Action.add]: this.add
    }
  },
  add(state, params) {}
}

Under the hood, Microcosm tags functions automatically.