node-mappable
Inherit from this base class to enable recursive mapping to a view-friendly object structure.
Use case
- You need to present objects to views. (JSON or HTML)
- Your objects need to selectively include properties and entities from the underlying data model.
- The properties and entities you present need to be transformed, asynchronously fetched or otherwise consistently mapped.
- You want to keep all this logic DRY. (see Don't repeat yourself)
Example
To output Assets from this object model:
Do this:
Asset;
Or for collections of Assets:
Asset;
See examples:
Installation
$ npm install mappable
How to use
Inherit from mappable Base
For each of the classes in your object model, inherit from Base.
{ MyClasssuper_;}util;
(If your class already inherits from something else, wrap instances using ViewContext or consider wrapping it within a class that inherits from Base.)
Define the mappings
MyClassprototype;
Define the default properties
MyClassprototype;
Convert a single mappable instance to a view object
Mappable#toViewObject(template, callback)
Arguments:
- template (optional) specifies which properties to include in addition to the default properties:
'*'
will include all properties available, recursively (not recommended for production)- Object to extend default properties, with values of either
true
or a sub-template Object, e.g.{ updatedAt: true, owner: { updatedAt: true }}
- callback function taking arguments for error and the new view object, e.g.
function(err, viewObject){}
Convert a custom object structure to a view object
Use a ViewContext instance to recursively convert a custom object containing instances.
var ViewContext = require('mappable').ViewContext;
ViewContext.create(obj)
Returns a new ViewContext instance.
Arguments:
- obj an Object containing individual instances or arrays of instances
ViewContext#map(mappings)
Returns the same ViewContext instance for chaining.
ViewContext#template(template)
Returns the same ViewContext instance for chaining.
ViewContext#toViewObject(template, callback)
See instance#toViewObject.
ViewContext#on(eventName, fn)
Events:
'error'
e.gfunction(err){}
'complete'
e.g.function(viewObject){}
Concurrency
The default is to run mapping operations in parallel. To limit the number of concurrent mappings:
require('mappable').setConcurrencyLimit(5);
Or, for series:
require('mappable').setConcurrencyLimit(1);