Node.js app for slicing and dicing paginated chunks of data with easy sorting and filtering.
Snapshot is added to the npm registry, and can therefore be downloaded with
npm install snapshot-js.
All dependencies can be installed with
bower install and
npm install, however the list is as follows:
Once a WebSocket connection has been successfully established, you're able to bootstrap Snapshot, passing in the WebSocket (Socket.IO) reference as a dependency.
var $snapshot = ;
You then need to tell Snapshot which collection it's going to be creating snapshots of. You can pass in an optional string for the
primaryKey – if you omit the
primaryKey then the first key of the first model is used.
primaryKey is an optional parameter.)
Snapshot listens for three events natively, and these are handled automatically.
snapshot/:namespace/perPage– Set amount per page;
snapshot/:namespace/pageNumber– Set current page number;
snapshot/:namespace/sortBy– Set order column and ascending/descending;
As Snapshot supports multiple instances, a namespace is used to distinguish the events. If you don't explicitly specify a namespace in the instantiation then it will be
default. Therefore all of your events will be:
:namespace is the name you provided upon instantiation of
Snapshot – if you didn't, then it's
When the collection has been updated, Snapshot emits the
snapshot/:namespace/contentUpdated event, passing through the snapshot as the first argument, and statistics relating to the request as the second argument.
For sorting by any given column, you can emit the
snapshot/:namespace/sortBy event passing in the
direction (ascending/descending). If you omit the
direction property (or set its value to
false) then Snapshot will cleverly invert the current sorting direction for you.
In addition to sorting and limiting, Snapshot also allows for the filtering of the collection. For this you can use the
applyFilter method. Unfortunately you will need to read Crossfilter's API Reference before you begin filtering – or for simple filtering you can use Snapshot's primitive in-built filters.
You can apply a filter however you like. It doesn't necessarily need to be applied via WebSockets, you could just as well use vanilla Node.js or Express.js. In our example though, we emit the
filterByWord event to the Node.js server, and then we need to listen for that event.
You essentially invoke the
applyFilter on the
snapshot object. Snapshot will pass in the
dimension argument to your lambda function –
this context is preserved. It's then entirely up to you to apply that dimension to the collection.
If you would like to clear a specific dimension, then you can use the
clearFilter method – which takes the property name as its one and only argument.
You can also clear every single filter by using the
In light of Crossfilter's learning curve, Snapshot comes bundled with a handful of in-built filters for common filtering techniques. These can all be invoked by emitting an event with a corresponding value.
Each in-built filter expects the event name (
snapshot/default/fuzzyFilter), the key (
word), and value (
By default when you apply a filter, the previous filter will be cleared which is mostly likely the behaviour you're looking for. However, what if the user clicks red, and then clicks blue? Wouldn't it be nice if we could filter by both red and blue? In that case you're looking for the third argument of the
afresh– filtering cleared before each filter;
reduce– filtering applied on current collection;
Since the browser does not download every model into the browser, it's impossible to determine what the minimum/maximum for any given key is without loading all models. Snapshot therefore allows you to specify which columns you wish to generate minimum/maximum ranges for.
Please be careful with these as too many may noticeably slow down your Snapshots.
The following would specify that you wish to retrieve the ranges for the
id property on every content change.
When the content changes you can access the range with
When instantiating Snapshot you should pass in the namespace for the current collection – that way you could create a new instance of
Snapshot with a unique collection of models.
var $dogs = 'dogs';var $cats = 'cats';var $rabbits = 'rabbits';
In the above example Snapshot will have 9 events to listen to (3 events * 3 snapshots):
And it will emit 3 events:
If you don't create a namespace then the namespace will be set to
There may be instances where sending delta updates is preferable to re-sending whole models. Snapshot supports the providing of delta updates – essentially, any models that have already been transmitted across the wire will not be sent again in their entirety; instead only their primary ID is sent.
var $snapshot = ;
Once you've enabled delta updates using
useDelta(true) as part of the bootstrap process, Snapshot will keep a history of transmitted models. It's crucial that you set the appropriate primary ID when invoking
setCollection, otherwise a default primary key will be assumed.
Since unique models will only ever be transmitted once, it's imperative that you keep a history of all models from the
snapshot/:namespace/contentUpdated event, and then to utilise those from your local cache when you come across a delta model.
Delta models are nothing more than the primary key of the model, which will help you lookup the model from your own collection cache. Therefore to detect a delta model, simply use something like
Number.isFinite (or Underscore's
_.isNumber) on the returned collection.
Snapshot comes bundled with an example to get you started.
example/client/index.htmlin your browser;
Below is a simple diagram of how Snapshot works. It demonstrates how the
snapshot/:namespace/pageNumber event operates – which is also the same way other native Snapshot events function. It also demonstrates the flow of custom filters.
snapshot/:namespace/pageNumberevent with data (example);
snapshot/:namespace/contentUpdatedevent with the updated collection;
customFilterApplied) with the data;
customFilterAppliedevent and then interacts with Snapshot;
snapshot/:namespace/contentUpdatedevent with the updated filter applied;
Grunt is a prerequisite to run the Mocha tests, which is installed when you run
npm install. Afterwards all of Snapshot's unit tests can be run with the
grunt test command from the terminal.
Snapshot also comes bundled with a handful of Cucumber tests.
bundle exec cucumber
Loading a large collection of models into the browser is slow and unnecessary, instead Snapshot uses WebSockets to serve snapshots of those models to the browser when requested. It retains the state of the models, and so if a filter is changed, or the page number incremented, it will modify the snapshot only for that client.
Snapshot is also tremendously fast because of its use of Socket.io and Crossfilter. Snapshot listens for events to change the state of the collection of models, and fires another event to let the client know the snapshot was updated. Crossfilter allows Snapshot to quickly slice and dice models – in the example, slicing and dicing takes 0-1 milliseconds for 1,000 models.
Since Snapshot uses Node.js, the browser support is that of Socket.io, which essentially means Snapshot supports Internet Explorer 5.5+.
snapshot/default/contentUpdatedwith first page's 50 models;
snapshot/default/contentUpdatedwith second page's 50 models;
snapshot/default/contentUpdatedto supply second page's red models;
snapshot/default/contentUpdatedto supply second page's red models ordered globally by colour;
You may wish to cache the collection loaded into Snapshot – for this we recommend something like RedisCache.