Steamer
In thick client web applications, one of the server's primary jobs is to load data and then simply relay it to the client. This task can be accomplished with less code and more clarity using a declarative (as opposed to an imperative) approach. Steamer is an tiny module that facilitates loading and relaying data declaratively.
Simplest example ever
steamer = ; var ssData = // Boats are divided into "containers" that hold data. // We will be sourcing data from a mongo collection called 'contacts'. contacts : collection : db // supply a reference to the collection // ... other containers go here ; ssData; // The `boat.stuff()` method asynchronously loads the data described by each container's manifest.ssData;
Example usage with Express
// app.js// Once our ducks are lined up loading and sending data in express.js apps is a one-liner. // Install some middleware to create a boat on every request object// with containers for our application's common data sources.app; // The Steamer express middleware can be used to automatically stuff a boat at req[ xyz ]// and attach its payload to `res.locals[ xyz ]` when `res.render` is called.app; app;
Then with a simple JSON dump, which we can do in our layout template,
doctype html5html head script. window.ssData = !{ JSON.stringify( ssData ) } body // ...
The array of contact data will be in the browser at window.ssData.contacts
. Wasn't that easy!
The power of containerization
Because containers are in charge of managing their own manifests and loading their own data (i.e. stuffing themselves), container classes can be designed to suit any data source or purpose. For example, you could easily define a redis container class that loads data by key name:
ssData; ssData
And since containers generate their own payload, they can structure it with consideration for how it will be consumed. For example, Steamer's built in mongo collection container will merge fields from multiple calls to boat.add()
, and ensure the _id
field is always supplied with each record:
ssData;ssData;ssData;
Reference
The Boat object
new Boat( containers )
Creates a new boat. containers
is a hash of named containers.
boat.add( itemsByContainer )
Adds items to the boat's manifest. itemsByContainer
is a hash of items to add, keyed by container name. The boat calls the add
method on each container with the supplied item for that container. Keys that do not correspond to a container are treated as "bulk cargo" and stuffed without transformation.
reqssData;
boat.reset()
Clears the boat's manifest by calling container.reset()
on each container.
boat.stuff( callback )
Calls stuff
on each of the boat's containers (in parallel), and callback( err, payload )
when done, where payload
is a hash of data keyed by container name (plus any "bulk cargo" entries).
Defining containers
Steamer only comes with a mongo collection container. It is up to you to define containers for other data sources. Containers must implement three methods, add
, reset
, and stuff
, which are called by the corresponding boat
methods. Let's see how to implement a redis container like the one we used above.
{ this_keys = ; this_client = optionsclient; // Save a reference to our redis client. return this;}; RedisContainerprototype { // Add an item, which can be a key or array of keys, to our manifest. this_keys = this_manifest;}; RedisContainerprototype { this_keys = ;}; RedisContainerprototype { async;};
Now we can initialize our boat with both a mongo container and a redis container.
app.use( function( req, res, next ) {
req.ssData = new steamer.Boat( {
contacts : new steamer.MongoCollectionContainer( {
collection : mongoDb.collection( 'contacts' )
} ),
session : new RedisContainer( { client : redisClient } )
} );
next();
} );
Easy.
The built-in mongo collection container
When instantiating the built in mongo collection container, pass it an options
object with a reference to the collection, as shown above. When adding to the container's manifest, supply a "selector" object:
reqssData;
fields
may be single field name, an array of field names, or an asterisk, indicating that all fields of the selected records should be included in the payload. The special_id
field is always included.where
can be any valid mongo query.sort
has the same semantics and format as in mongo'scursor.sort()
.skip
andlimit
have the same semantics as mongo'scursor.skip()
andcursor.limit()
You can also provide an array of selector objects (equivalent to calling boat.add()
once for each selector):
reqssData;
License
MIT