Substance.js

Substance.js is a framework for quickly create RESTful APIs with Express.js and Mongoose.js

Usage

Mongoose is required. In terminal: npm install mongoose --save

Defining resource

  
  var substance = require('substancejs')
    , config = require('./config.json')
    , modelReview = require('./modelReview')
    , Schema = require('mongoose').Schema
    , app = substance({
      mongoose:{
        uri: config.uri,
        options: config.options
      }
    });
  
  app.resource( 
    'user',           // resource name
    {                 // resource data schema
      username: String,
      email: String
    },
    {
      defaults: function( resource ){ ... },
      namespace: undefined  // add base for mount path
    }
  );
  
  app.resource('place', new Schema({ /* ••• */ }));
  
  app.resource('review', modelReview);
  
  app.resource('place')
      .beforeAll( /* passport.js auth */ )
      .before('create', function( req, res, next ){
          req.body.author = req.body.editor = req.user;
          
          next();
      })
      .before('update', function( req, res, next ){
          req.body.editor = req.user;
          
          next();
      })
      .after('list', function( req, res, result, next ){
        this; // context == Resource
        this.model // == mongoose.model('place');
      
        this.model.count(req.query.filters, function(err, countPlaces){
          result.meta.total = countPlaces;
          next(null, result);
        });
      })
  
  
  app.listen(3000, function(){
    console.log('Substance listening at http://localhost:3000');
  });
  

Done! Now you have the following routes:

HTTP	Address	Notes
GET	/users	Get a collection of resources, accepts query: filters, fields, sort, limit, skip, populate
POST	/users	Create a resource
GET	/users/:id	Get a specific resource
PUT	/users/:id	Update a resource
DELETE	/users/:id	Delete a resource

Before and after transformation

If you need to validate the input data or to wrap up the output, then you can use transformers before and after.

beforeAll and afterAll transformer will be called before other!

  app.resource( 'user', schema, options )
        .before( 'list', function( req, res, next ){
            QueryPreparing(req.query);
            
            next();
        })
        .before( 'create', function( req, res, next ){
            ValidateBodyParams(req.body);
            
            if(req.validateErrors){
              next(req.validateErrors);
            }else{
              next();
            }
        })
        .afterAll(function( req, res, result, next ){
            next( null, { result: result, count: result.length });
        })
        
  // Multi
  
  app.resource( 'user' )
        .before( 'create', 'update', something_func  )
        .after('list', 'read', func_1, func_2 )

By default, in Substance has set the following transformers

Stage	Action	Transformation
beforeAll	---	Parse input value by type (type conversion). Example 'true' --> true
beforeAll	---	Validation the parameters that will be passed in Mongoose Query
before	create	Check Content-Type header (only 'application/vnd.api+json' or 'application/json')
before	create	Remove unnecessary fields from req.body (_id, updated, created, author, editor)
before	update	Check Content-Type header (only 'application/vnd.api+json' or 'application/json')
before	update	Remove unnecessary fields from req.body (_id, updated, created, author, editor)
after	list	Add meta field and count (length of result) in meta field
after	list	Add total field in meta (total count of data by filters)
afterAll	---	Wrap all result in result field

Override default method

You can override default method:

  app.resource('another')
        .create( my_create_func ) // override create function. Args req, res, next
        .read( my_read_func )
        .list( my_list_func )
        .update( my_up_func )

Custom method

  app.resource('review')
        .method('post /:id/block', method_for_review) // now you have  POST /reviews/:id/block method
        .before('post /:id/block', before_block) // and hook for custom method

Set global methods and hooks by default

If you want to set for all or for some resources their methods and hooks, you can set options 'defaults'.

    var defaults = function( resource ){   
            resource.create( MyCreateFunc );
            resource.beforeAll( MyHookFunc ); 
        }
      , app = substance( { ..., defaults: defaults}) // for all resources
      
      // OR
      
      app.resource('Name', SchemaOrModel, { defaults: defaults }) // for current resource

Clear hooks

    app.resource('review').clear('before'); // remove all before hooks
    app.resource('review').clear('beforeall'); // remove all beforeall hooks
    app.resource('review').clear('before', 'create'); // remove all before create hooks
    app.resource('review').clear('before', 'put /reviews/:id/photos'); // remove all before custom method hooks

Debug

Substance uses the debug module internally to log information about route matches and application mode. To see this information, simply set the DEBUG environment variable to substance:* when launching your app and the debug information will appear on the console.

   DEBUG=substance* node app.js