What purpose does `req.options` serve in SailsJS?

Question

What purpose does req.options serve in SailsJs?

From the source, it seems I can somehow use policies to alter existing params on Sails Blueprints, etc. How does this work? I can't find any documentation at all.

Answer 1

req.options was introduced in Sails v0.10 as a way to add options to custom routes. For example, you could always do:

'GET /userList': {
    controller: 'UserController', 
    action: 'find'
}

to point at the default "find" action for a User model, but there was no way to control the query--it would always just return all records. Now you can do:

'GET /userList': {
    controller: 'UserController', 
    action: 'find',
    sort: 'name desc',
    where: {name: {startsWith: 'j'}}
}

and all of the options (including controller and action) will be added to req.options, which the default blueprint actions use to modify the query. Note the difference to Sails v0.9.x, which used req.target to keep track of the controller and action.

As you pointed out, req.options can also be modified within policies, as opposed to req.params which are reset before every policy and controller action. This can be used to, for example, further restrict the criteria for a query based on a user's role.

Obviously the docs for v0.10.x aren't completely finished (and will always be subject to improvement), but this could definitely find a place in the Route Target Syntax section...