Skylight
The (Experimental!) Skylight library simplifies the construction of real-time collections.
Core Values
Real-time collections are difficult to do well unless you have your priorities set straight.
In order of importance, here are the goals of Skylight:
-
Correctness
Skylight is a thin but bulletproof interface between your database and client.
-
Simplicity
Simplicity allows consumers of Skylight to create understandable and well behaved collections.
-
Performance
Without compromising on correctness or simplicity, Skylight is fast.
Nomenclature
The Skylight
class is an extension of Backbone.Collection
. Think of Skylight
as a window into your data -- you can see your data, but you can't change it. Whereas normal Backbone collections change when you call methods like add
and sync
, Skylight
collections only change when your database changes.
A pair of Manager instances are required. One goes on the server, and the other on the client. They are named ServerManager
and ClientManager
respectively. The job of the Managers is to bridge the communication gap between server and client.
API
ServerManager
The ServerManager
requires more parameters than the ClientManger
because it has to communicate with your database.
var serverManager = // Passed directly to your collections to use. Backend Agnostic! db: db // Must be an EventEmitter that emits 'change' events // when a record changes, passing the record as the first argument dbFeed: feed // Passed directly to your collections to use, useful for storing user // roles and permissions so you can use them in filters context: context // A map of Skylight collections like: // {CustomCollection: require('./collections/custom')} manifest: manifest // Socket must be an EventEmitter that emits ClientManager eventsserverManager
ClientManager
The ClientManager
is simple to set up because it simply reflects what the ServerManager
sees on the server.
var clientManager = // Socket must be an EventEmitter that emits ServerManager events serverFeed: socket
Instance Methods
ClientManager.create(CollectionConstructor, optionsObject)
The create
method returns a collection with the specified options. If a duplicate collection already exists, you will get an identical instance. Otherwise, a new instance will be returned.
var myInstance = clientManager
Skylight
Skylight
uses progressive enhancement to give users some control over how simple or performant they want their collections to be.
The Minimum Collection
Skylight
subclasses require at minimum:
- An
_id
property that uniquely identifies this type of collection - A
_fetch
method that gets the data for the collection
Skylight
I was verbose with the above example so I could explain the data that the _fetch
callback expects. In reality, your simplest collections would look similar to this:
Skylight
Incremental Updates
Instead of performing a fetch for every change, you can implement an optional _onChange
method that is called each time the ServerManager
's dbFeed
emits a change
event.
You can get very creative with your _onChange
method, but here is a typical one that has logic for adding, editing, and removing models.
Skylight
Take a little time to understand the annotated example above. The _onChange
method is a powerful and unopinionated way to perform incremental updates -- even asynchronous ones!
Since incremental updates are inherently more tricky to get right, here is the above example without the annotations so that you can use it as a template:
Skylight
Instance Methods
Skylight.loaded
The loaded method calls the callback when the collection is done retrieving its initial payload.
instance
Skylight.setOptions
This method allows you to change the options of a collection on-the-fly. The callback is called after the options have been set, and the new data has loaded.
instance