mongoose-ability

Mongoose plugin for managing users' abilities.

How to install

npm install mongoose-ability

How to use

1. Hook the plugin to a schema:

// user.js
const Promise = require('bluebird');
const { Schema, model } = require('mongoose');
const abilityPlugin = require('mongoose-ability');

const schema = new Schema({
  name: String
});

schema.plugins(abilityPlugin, {
  name: 'removeUser',
  verifier(user) {
    if(!user) {
      return Promise.resolve(true);
    }

    return Promise.resolve(this.equals(user));
  },
  error: new Error('Removing the user is forbidden by the user') // Define a custom error (optional)
});

verifier and name are required options for the plugin. name defines names of the methods generated by the plugin which are in format canActionName and canActionNameOrError. In example's case generated methods are canRemoveUser and canRemoveUserOrError. verifier is a function which verifies the ability by returning a promise which returns either true (action is permitted) or false (action is forbidden). verifier gets the same arguments as canActionName and canActionNameOrError methods. error is optional error parameter which will be rejected when using canActionNameOrError and action is forbidden.

2. Validate abilities (Express example):

  const User = require('./user');

  app.delete('/users/:userId',
    authorize(),
    (req, res, next) => {
      let targetUser;

      User.findById(req.params.userId)
        .then(user => {
          if(!user) {
            return next(new Error(`Couldn't find user by id "${req.params.userId}"`));
          }

          targetUser = user;

          return req.user.canRemoveUserOrError(user); // rejects if verifier returns false
        })
        .then(() => targetUser.remove())
        .then(() => res.sendStatus(200))
        .catch(next);
    });

Running tests

npm test