docs(ability): adds details about merging permissions

Closes #43

Author: stalniy

docs/_posts/2017-07-23-use-cases.md

@@ -3,7 +3,7 @@ layout: default
 title:  "Other interesting use cases"
 date:   2017-07-23 9:40:48 +0300
 categories: [abilities]
-tags: [merging abilities, feature flags, hardware capabilities]
+tags: [merging abilities, merge permissions, combine rules, feature flags, hardware capabilities]
 ---
 
 The primary goal of CASL is to provide a simple way to declare user abilities in application. In the same time application may or may not have some capabilities depending on hardware, user's culture, subscription plan, etc. Lets see how these cases can be covered by CASL.
@@ -31,31 +31,56 @@ const ability = AbilityBuilder.define(can => {
 
 And later in UI check the capability with help of `ability.can('read', 'wifi')`. You can mix these definitions with your permission logic if you need. In this way, you have 2 levels of permission: device level (whether such capability exists at all) and role/subscription level (whether a user has the right to do this). But be careful with the order of rules. See [Combining Abilities][combining-abilities] for details.
 
-The better way would be to create 2 instances of `Ability`: 1 for hardware capabilities another for permission based system and then use them together:
+The better way would be to create 2 functions which defines:
+* hardware capabilities
+* and another for permission based system
+
+Hardware should forbid user to do allowed action if it doesn't support that action. That means hardware permissions need to be defined using `cannot` DSL function
 
 ```js
-const hardwareAbility = AbilityBuilder.define(can => {
-  if (capabilities.version >= 10) {
-    can('manage', 'Wifi')
+function hardwarePermissions(capabilities) {
+  const { cannot, rules } = AbilityBuilder.extract()
+
+  if (capabilities.version < 10) {
+    cannot('manage', 'Wifi').because('Device does not support Wifi')
   }
 
-  can(....)
-  ....
-})
+  cannot(...)
+
+  return rules
+}
+```
+
+User permissions can be defined as usually:
+
+```js
+function userPermissions(user) {
+  const { can, rules } = AbilityBuilder.extract()
 
-const userAbility = AbilityBuilder.define(can => {
-  if (user.isAdmin) {
+  if (user.role === 'admin') {
     can('manage', 'all')
   } else {
     can('read', 'all')
   }
-})
 
-if (hardwareAbility.can('manage', 'Wifi') && userAbility.can('manage', 'Wifi')) {
-  // show wifi settings page
+  return rules
 }
 ```
 
+Now, we can merge them and create `Ability` instance. As hardware capabilities should override role permissions, it should be added at the end (rules order matters, see [Combining Abilities][combining-abilities] for details)
+
+```js
+// `capabilities` is an object, represents hardware capabilities, usually provided by hardware API
+// `user` is an object, represents information about user details, usually provided by server API
+
+const rules = userPermissions(user)
+  .concat(hardwarePermissions(capabilities))
+
+const ability = new Ability(rules)
+
+ability.can('manage', 'Wifi')
+```
+
 ## Feature flags
 
 Also you can use CASL to define feature flags and run [A/B testing](https://en.wikipedia.org/wiki/A/B_testing) for new features.