📃 docs: update

README.md

@@ -21,15 +21,46 @@ The Attribute-Based Access-Control Library let you define five `can` access abil
 
 ## Quick Start Guide
 
-> Read more on defining `scoped` `action` and `object` ability in this [link](https://vhidvz.github.io/blog/post-abac/).
+### ABAC vs RBAC?
+
+| **Question**       | **RBAC**                          | **ABAC**                                    |
+| ------------------ | --------------------------------- | ------------------------------------------- |
+| Who can access?    | :heavy_check_mark:                | :heavy_check_mark:                          |
+| How can operate?   | :white_check_mark: CRUD           | :heavy_check_mark: With more options        |
+| What resource?     | :white_check_mark: Not Bad At All | :heavy_check_mark: More control on resource |
+| Where user can do? | :x:                               | :heavy_check_mark: Supported by IP and CIDR |
+| When user can do?  | :x:                               | :heavy_check_mark: Supported by CRON        |
+| Best structure?    | Monolithic Apps                   | PWA, Restfull, GraphQL                      |
+| Suitable for?      | Small and medium projects         | Medium and large projects                   |
+
+### What's Scope?
+
+Definition as a verb is:
+
+- look at carefully; scan.
+- assess or investigate something.
+
+In this library, I have scoped `action` and `object` which means you can have more control over these attributes.
+
+Assume you have a publisher website with four types of users with the following roles:
+
+- `admin` super user can do anything
+- `manager` can do anything on articles
+- `guest` can read only published article
+- `user` the writers with limitations on time and location of article creation.
+
+In microservice design patterns and restful's based on my opinion one of the best practices has focused on resource management, a single endpoint with a concentration on objects is better than having multiple endpoints or having complex business logic.
+
+Now, if you want to handle all these policies in one place (e.g. `GET endpoint` read permission) how you can do this?
+we suppose you use the `scoped` policy or `ability` grant definition instead of having multiple endpoints or having complex business logic.
 
 ### installation
 
 ```sh
 npm install --save abacl
 ```
 
-### Usage
+### Usage and Dangling
 
 Define your user policies as a json array, so you can store it in your database:
 
@@ -122,7 +153,7 @@ const article = {
 Create a new access control object, then get the permission grants:
 
 ```ts
-import AccessControl, { normalize } from 'abacl';
+import AccessControl from 'abacl';
 
 // The `strict` `AccessControlOption` control the scoped functionality
 // default strict value is true, you can change it on the `can` method
@@ -131,7 +162,7 @@ const ac = new AccessControl(policies, { strict: false });
 const permission = ac.can([user.subject], 'read', 'article');
 
 // change strict mode dynamically, Example:
-// const strictPermission = ac.can([user.subject], 'read', 'article', undefined, { strict: true });
+// const strictPermission = ac.can([user.subject], 'read', 'article', { strict: true });
 
 /**
  *   it('should change strict mode dynamically', () => {
@@ -140,7 +171,7 @@ const permission = ac.can([user.subject], 'read', 'article');
  *     expect(ac.can([Role.User], 'read', 'article:published').granted).toBeFalsy();
  *
  *     // After changing strict mode
- *     expect(ac.can([Role.User], 'read', 'article:published', undefined, { strict: false }).granted).toBeTruthy();
+ *     expect(ac.can([Role.User], 'read', 'article:published', { strict: false }).granted).toBeTruthy();
  *   });
  *
  * */

docs/classes/AccessControl.html

@@ -29,7 +29,7 @@ <h4>Hierarchy</h4>
 <ul class="tsd-hierarchy">
 <li><span class="target">AccessControl</span></li></ul></section><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L12">classes/acl.class.ts:12</a></li></ul></aside>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L12">classes/acl.class.ts:12</a></li></ul></aside>
 <section class="tsd-panel-group tsd-index-group">
 <section class="tsd-panel tsd-index-panel">
 <details class="tsd-index-content tsd-index-accordion" open><summary class="tsd-accordion-summary tsd-index-summary">
@@ -80,19 +80,19 @@ <h5><span class="tsd-kind-parameter">policies</span>: <a href="../interfaces/Pol
 <h5><code class="tsd-tag ts-flagOptional">Optional</code> <span class="tsd-kind-parameter">options</span>: <a href="../interfaces/ControlOptions.html" class="tsd-signature-type tsd-kind-interface">ControlOptions</a></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <a href="AccessControl.html" class="tsd-signature-type tsd-kind-class">AccessControl</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L16">classes/acl.class.ts:16</a></li></ul></aside></li></ul></section></section>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L16">classes/acl.class.ts:16</a></li></ul></aside></li></ul></section></section>
 <section class="tsd-panel-group tsd-member-group">
 <h2>Properties</h2>
 <section class="tsd-panel tsd-member tsd-is-protected"><a id="options" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagProtected">Protected</code> <code class="tsd-tag ts-flagReadonly">Readonly</code> <span>options</span><a href="#options" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-property">options</span><span class="tsd-signature-symbol">:</span> <a href="../interfaces/ControlOptions.html" class="tsd-signature-type tsd-kind-interface">ControlOptions</a><span class="tsd-signature-symbol"> = {}</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L13">classes/acl.class.ts:13</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L13">classes/acl.class.ts:13</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member tsd-is-protected"><a id="present" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagProtected">Protected</code> <span>present</span><a href="#present" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-property">present</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type ">Record</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">, </span><a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol"> = {}</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L14">classes/acl.class.ts:14</a></li></ul></aside></section></section>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L14">classes/acl.class.ts:14</a></li></ul></aside></section></section>
 <section class="tsd-panel-group tsd-member-group">
 <h2>Accessors</h2>
 <section class="tsd-panel tsd-member"><a id="policies" class="tsd-anchor"></a>
@@ -102,7 +102,7 @@ <h3 class="tsd-anchor-link"><span>policies</span><a href="#policies" aria-label=
 <li class="tsd-description">
 <h4 class="tsd-returns-title">Returns <a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">[]</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L31">classes/acl.class.ts:31</a></li></ul></aside></li>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L31">classes/acl.class.ts:31</a></li></ul></aside></li>
 <li class="tsd-signature" id="policies.policies-2"><span class="tsd-signature-symbol">set</span> policies<span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">policies</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">void</span></li>
 <li class="tsd-description">
 <div class="tsd-parameters">
@@ -112,7 +112,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
 <h5><span class="tsd-kind-parameter">policies</span>: <a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">[]</span></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L25">classes/acl.class.ts:25</a></li></ul></aside></li></ul></section></section>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L25">classes/acl.class.ts:25</a></li></ul></aside></li></ul></section></section>
 <section class="tsd-panel-group tsd-member-group">
 <h2>Methods</h2>
 <section class="tsd-panel tsd-member"><a id="can" class="tsd-anchor"></a>
@@ -133,7 +133,7 @@ <h5><span class="tsd-kind-parameter">object</span>: <span class="tsd-signature-t
 <h5><code class="tsd-tag ts-flagOptional">Optional</code> <span class="tsd-kind-parameter">options</span>: <a href="../interfaces/CanOptions.html" class="tsd-signature-type tsd-kind-interface">CanOptions</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <a href="Permission.html" class="tsd-signature-type tsd-kind-class">Permission</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L58">classes/acl.class.ts:58</a></li></ul></aside></li></ul></section>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L58">classes/acl.class.ts:58</a></li></ul></aside></li></ul></section>
 <section class="tsd-panel tsd-member"><a id="delete" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>delete</span><a href="#delete" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <ul class="tsd-signatures">
@@ -146,7 +146,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
 <h5><span class="tsd-kind-parameter">policy</span>: <a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">boolean</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L39">classes/acl.class.ts:39</a></li></ul></aside></li></ul></section>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L39">classes/acl.class.ts:39</a></li></ul></aside></li></ul></section>
 <section class="tsd-panel tsd-member"><a id="exists" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>exists</span><a href="#exists" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <ul class="tsd-signatures">
@@ -159,7 +159,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
 <h5><span class="tsd-kind-parameter">policy</span>: <a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">boolean</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L35">classes/acl.class.ts:35</a></li></ul></aside></li></ul></section>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L35">classes/acl.class.ts:35</a></li></ul></aside></li></ul></section>
 <section class="tsd-panel tsd-member"><a id="update" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>update</span><a href="#update" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <ul class="tsd-signatures">
@@ -174,7 +174,7 @@ <h5><span class="tsd-kind-parameter">policy</span>: <a href="../interfaces/Polic
 <h5><span class="tsd-kind-parameter">deep_copy</span>: <span class="tsd-signature-type">boolean</span><span class="tsd-signature-symbol"> = true</span></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L43">classes/acl.class.ts:43</a></li></ul></aside></li></ul></section></section></div>
+<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L43">classes/acl.class.ts:43</a></li></ul></aside></li></ul></section></section></div>
 <div class="col-sidebar">
 <div class="page-menu">
 <div class="tsd-navigation settings">