enhanced-sails-blueprints

---

These blueprints have been extracted from one of my other projects Backbone.Sails. During the development of that plugin, I did my utmost best to avoid having to touch the server-side. However, the default sails blueprints (as of v0.10) didn't support all the features I wanted & didn't seem to have been tested much with the resourceful socket events.

Some problems which arose...

• When you send a POST request which is intended to create a new model, if it has any nested models, those models will be sent straight into waterline and the resourceful 'created' event will not fire. This is a really, really big problem for realtime applications.

• Sails will try to parse query parameters, as well as the body, to derive attributes to be persisted on a model. These blueprints only check the body, allowing you to write policies which test certain attributes within the http body.

• In the same vein, where, sort and limit criteria can only be specified as query parameters. Sails would check the body for these as well, which is just plain annoying.

• When persisting associated collections via the 'create' and 'update' blueprints, the resourceful addedTo and removedFrom events wouldn't fire. These blueprints fix that.

• The sort criteria could only be a simple string ("name ASC") when passed as a query parameter. This limits your ability to do a primary sort and a secondary sort. These blueprints allow you to pass JSON describing the sort criteria, allowing you to sort on however many attributes you wish. For example 'GET /user?sort={"lName": 1, "fName": 1}' would sort by last name ascending, and then first name ascending.

• There is no populate criteria. That's right folks, the best you can do is specify which attributes to populate, and sails would then go ahead and populate those, using the default limit for associated collections (30 by default). This is a real pain, suppose I wanted all the books associated to a library beginning with "L" through get request to library? Not do-able. Well... now you can with enhanced-sails-blueprints. Simply pass 'populate' as a query parameter, and send down a JSON describing the criteria (see waterline github repo) you would like to populate with...

  'GET /library?populate={ "books": {"where": { "name": { "startsWith": "L" }, "limit": 5000 } } }'

• Waterline doesn't support self referencing many-to-many. (see stackoverflow question) Yup, a person may have friends, but you need those friends to have a person (as a friend). This is a nuisance to pull of with waterline. These blueprints are at your disposable, for they will inspect your waterline models, and, if the convention adopted is satisfied, you can support self-referencing many-to-many attributes without any extra front-end code. Here is an example model declaration demonstrating the semantics required to kick start this functionality:

  Person.js

  module.exports= {
    attributes: {
      friends: {
        collection: "person",
        via: "_friends",
        dominant: "true"
      },
      
      _friends: {
        collection: "person",
        via: "friends"
      }
    }
  }
  

  Above, the 'friends' attribute is the one to be used publicly. When a personA.friends is updated with a personB, then personB.friends needs to be updated with personA - a pain! These blueprints will add personB to personA.friends as well as personA._friends. When this is sent down to waterline, it'll pick up the 'via' clause and automatically push personA to personB.friends (as well as personB._friends). Which effectively maintains a mutual relation. This is the best way of doing this for now. It is well supported, firing all the resourceful events you'd expect, and it works fine when one person is deleted.

• + many more minor tweaks, bug fixes, performance & security enhancements

These blueprints have pretty exhaustive testing through both AJAX and socket requests. You can find the test code here.

In conclusion...

You need these blueprints!

Ok, so how do I install them?

• Clone the repo or download the zip
• Copy the /blueprints folder to your /api folder
• Install lodash and bluebird on your server side
  • npm install lodash --save
  • npm install bluebird --save