Ability.merge

[stalniy]

Allows to merge 2 and more Ability instances into. Only Ability instances with the same options can be merged together, otherwise exception should be thrown.

This feature will allow to merge rules of few abilities, basically this is a helper method for doing the next thing:

ability.update(ability.rules.concat(anotherAbility.rules))

This may be useful if you want to define some rules dynamically in the database and some statically in the code

Design:

Merged abilities are added at the end

const hardwareAbility = AbilityBuilder.define(can => {
   ...
})

const userAbility = AbilityBuilder.define(can => {
  ...
})

const ability = userAbility.merge(hardwareAbility)

In this case, hardwareAbility may enforce/overwrite any userAbility. ability is modified and hardwareAbility is not changed, update and updated events are emitted on Ability instance.

In case userAbility and hardwareAbility has different options for subject detection (i.e., subjectName) Ability.merge should throw an error telling that merged abilities are not compatible

[stalniy]

After some thinking and writing code I decided that such function just adds complexity and requires to answer on additional questions, like:

1. When we merge abilities how should be they merged? At the end of existing Ability rules or at the beginning (i.e., push vs unshift).
2. Should this function accept 1 or endless amount of arguments?
3. Should it accept arrays?

In most cases, such functionality will be needed only backend side, so it would be good not to pollute frontend bundle with code which will never be used.

To achieve the same functionality we can do this:

// should define `cannot` rules
function hardwareRules() {
  const { can, cannot, rules } = AbilityBuilder.extract()

  if (!hardware.supports('wifi')) {
    cannot('manage', 'wifi')
  }

  cannot(...)

  return rules
}

function userRules(user) {
  const { can, cannot, rules } = AbilityBuilder.extract()

  can(...)
  cannot(...)
  can(...)

  return rules
}

const ability = new Ability(userRules(user).concat(hardwareRules()))

So, a user is able to split rules (instead of Ability instances) into different functions and combine them in whatever way is better for his app.

[stalniy]

I will update documentation with the example above and close this issue

[stalniy]

Example and explanation is added in https://stalniy.github.io/casl/abilities/2017/07/23/use-cases.html