Data flows

Orbit enables the coordination of many independent sources of data, each of which may internally handle queries and updates differently. It’s easy to imagine tying oneself in knots with such potential complexity. However, by following Orbit’s conventions and a few guidelines, you can compose data to flow predictably and reliably through your application.

“Request up, sync down”

Orbit divides the movement of data into two different “flows”:

Every source interface has events and methods that correspond with one of these flows:

“Request up, sync down” is a variant of the “data down, actions up” mnemonic popularized in the Ember.js community. In fact, most frontend frameworks adopt a similar pattern for handling actions and returning data. Orbit fits well with these patterns: an action triggered by a user can spawn an Orbit “request”, which can lead to responses that “sync” data back down, typically ending in an update to a view. In this way, “request up, sync down” can be seen as a continuation of the “data down, actions up” pattern.

Coordinating sources

Request and sync flows can be coordinated across sources by configuring an event listener for one source that triggers actions on another.

Let’s take a look at what events can trigger other actions:

Blocking vs. non-blocking

We can coordinate sources through simple event listeners, such as:

memory.on("beforeUpdate", transform => {

The above listener is “non-blocking” because it doesn’t return anything to the emitter. The call to remote.push() is async and may take a while to complete, so it will proceed in parallel with the memory source being updated.

As an alternative, we can use a “blocking” strategy in our event listener by simply returning a promise:

memory.on("beforeUpdate", transform => remote.push(transform));

This will prevent the memory source from updating before the transform has been pushed up to the remote source. An error in remote.push will cause memory.update to error as well.

Coordination guidelines

Here are some guidelines for working with data flows:

Last but not least, it’s recommended that you use a Coordinator instead of manually configuring event listeners. Read on to understand why …