Orbit is a library for coordinating access to data sources and keeping their contents synchronized.

Orbit provides a foundation for building advanced features in client-side applications such as offline operation, maintenance and synchronization of local caches, undo / redo stacks and ad hoc editing contexts.

Orbit relies heavily on promises, events and low-level transforms.

• Support any number of different data sources in an application and provide access to them through common interfaces.

• Allow for the fulfillment of requests by different sources, including the ability to specify priority and fallback plans.

• Allow records to simultaneously exist in different states across sources.

• Coordinate transformations across sources. Handle merges automatically where possible but allow for complete custom control.

• Allow for blocking and non-blocking transformations.

• Allow for synchronous and asynchronous requests.

• Support transactions and undo/redo by tracking inverses of operations.

Orbit.js is dependent upon Immutable.js for immutable data structures, and RxJS for observables.

Orbit.js must be used in an environment that includes an implementation of the Promises/A+. If you wish to support legacy browsers, you will need to include a library such as RSVP.

You'll need to configure Orbit to recognize any applicable dependencies.

Orbit defaults to using the global Promise constructor, if it exists. If your environment does not implement Promises, or if you wish to use another Promise implementation, configure your promise library's Promise constructor as follows:

Orbit.Promise = RSVP.Promise;

If you're using an Orbit source that relies on an ajax method (such as JSONAPISource), configure it as follows:

Orbit.ajax = jQuery.ajax;

Other sources may have other configuration requirements.

Orbit requires that every data source support one or more common interfaces. These interfaces define how data can be both accessed and transformed.

The methods for accessing and transforming data return promises. These promises might be fulfilled synchronously or asynchronously. Once fulfilled, events are triggered to indicate success or failure. Any event listeners can engage with an event by returning a promise. In this way, multiple data sources can be involved in a single action.

Standard connectors are supplied for listening to events on a data source and calling corresponding actions on a target. These connectors can be blocking (i.e. they don't resolve until all associated actions are resolved) or non-blocking (i.e. associated actions are resolved in the background without blocking the flow of the application). Connectors can be used to enable uni or bi-directional flow of data between sources.

The Orbit Common library (namespaced OC by default) contains a set of compatible data sources, currently including: an in-memory cache, a local storage source, and a source for accessing JSON API compliant APIs with AJAX.

You can define your own data sources that will work with Orbit as long as they support Orbit's interfaces. You can either make sources compliant with the Orbit Common library or use Orbit's base interfaces to create an independent collection of compatible sources.

Install the CLI for Broccoli globally:

npm install -g broccoli-cli

Install the rest of Orbit's dependencies:

npm install

Distributable versions of Orbit can be built to the /build directory by running:

npm run build

Orbit can be tested in CI mode by running:

npm test

Or directly with testem (useful for configuring options):

testem ci

Orbit can be tested within a browser (at http://localhost:4200/tests/) by running:

npm start

Or directly with broccoli (useful for configuring the port, etc.):

broccoli serve

Generate docs in the /docs directory:

npm run docs

Copyright 2016 Cerebris Corporation. MIT License (see LICENSE for details).