Coherence
Models and Intents, for your React app. Inspired by Flux.
Usage
Installation
npm install coherence
var Coherence = ;
Coherence is provided as a Node module, and has been used with Browserify for client-side code. If you've used another bundling tool for client-side usage, let me know!
Intents
Intents describe things that somebody wants to happen in your app. "Somebody" might be you, the programmer, or the user. "Things" might be choosing a background color, sending a message, opening a form, or pre-fetching data from the server.
Intents in Coherence are analogous to Actions and the Dispatcher(s) of Flux.
Intents are defined by a yielding function, which defines any input, and the output payload provided to the intent's subscribers, whenever the Intent is declared.
An popular pattern within the Flux community seems to be of "Action creators". These are a middle ground between Intents, and using a bare Dispatcher, and, I think, a step in the right direction. However, I think they don't go far enough.
Coherence eschews a Dispatcher, and Action creators, in favor of individually subscribable Intents, for the following reasons:
- The main advantage of a the Dispatcher is that it can resolve inter-store
dependencies. However, I disagree that an Action emitter (Dispatcher) is the
right place to encode state dependencies. Coherence is designed to let you
you implement models outside its purview, which resolve internal state
dependencies, and still expose those models' state to your view layer, with
Coherence.Model
s. - Having stores switching on Action "type" strings is error-prone, without some boilerplate safety around it. On the other hand, you can't subscribe to an Intent that hasn't been defined. This is only partially addressed by the Action creators, in that they make it less likely to create the wrong actions, but no more likely that stores respond to the right ones.
Defining Intents
// speak.js var Coherence = ; var Speak = Coherence; moduleexports = Speak;
// choose-animal.jsvar Coherence = ; var ChooseAnimal = Coherence; moduleexports = ChooseAnimal;
Declaring Intents
When something should actually happen in your app, you declare an Intent.
// react component ... { ; }
Responding to Intents
Intent subscriptions are the implementations of your application's behavior, in response to Intent declarations.
Speak;
Coherence.LocationFactory: Optional pushState and replaceState support
If you'd like to use path-based Intents, you can use
Coherence.LocationFactory
to define Intents that will update history, and the
URL, for you.
This allows your app to handle deep-linking, and browser back/forward, using the same patterns used for any other activity in your application.
// navigate.jsvar Coherence = ; // passing in window enables pushState, replaceState, and onpopstate support,// for browsers that support those featuresvar Location = Coherence; moduleexports = Location;
-
Location.Navigate(path)
- Yields
path
to subscribers, and updates the URL via pushState, if enabled. path
should be a string.
- Yields
-
Location.Redirect(path)
- Yields
path
to subscribers, and updates the URL via replaceState, if enabled. path
should be a string.
- Yields
-
Location.subscribe(subscription)
- adds a subscriber, which is called whenever Location changes via calls to
Navigate
orRedirect
. Subscription is passed a single argument: whateverpath
is passed toNavigate
orRedirect
.
- adds a subscriber, which is called whenever Location changes via calls to
Location Intents yield the path to subscribers, so that you can bring your preferred routing solution.
Defining view state models
Models define component-bindable information. You can house your business logic here, but anything complex should probably be pushed into classes of your own creation.
For Intent declarations to effect changes in your views:
- your views should be bound to Models
- Intent subscriptions should eventually call your Models' methods
- your Models' methods should modify view-exposed state
// animals-model.jsvar Model = Model;var Speak = ; var { var getAnimalAsync = dependenciesgetAnimalAsync; var model = ; // Intent subscriptions can be set up when you instantiate your model, or // where ever else it is convenient Speak; return model;}; moduleexports = Animals;
Integrating Coherence Intents and Models with React
var animalStore = instance;var Speak = ; var animals = instance; var AnimalView = React;
Features
Binding a Model to a React component
Within the context of a React class definition:
-
this.bindings = model.ReactBindings(this, bindMap)
- binds the component to update its state, whenever values are pushed to exposed state.
this
is the React componentbindMap
can be either be- an object, mapping exposed subject names, to component state properties
- or it can be omitted, to bind all of the model's attributes to the component,
with the names defined by
expose
- be careful to avoid binding naming collisions, we currently don't do anything to protect against that
-
this.bindings.unbind()
- cleans up the bindings set up by
model.ReactBindings
. Call this fromcomponentWillUnmount
- cleans up the bindings set up by
Development
Add or modify tests to reflect the change you want.
Run them with npm test
, and update the code in src/
till your tests pass.
Running the tests will run npm run compile
, which outputs the code as ES5,
polyfilled via core-js
.