GAPI-24749: Documentation update (add timeout, bulkhead, cache, and f…

…allback)

README.md

@@ -1,8 +1,10 @@
 # Mollitia
 
-> JavaScript Resilience Library
+<!-- TODO Badges -->
 
-<!-- TODO Description -->
+`Mollitia` is a **JavaScript Resilience** library that works on Node and on browsers.
+The purpose of such kind of tool is to help organize **asynchronous operations** under a highly customizable circuit that helps managing error use cases.
+When everything is falling apart, it stops the classic flow and uses modules to manage failures.
 
 ## Documentation
 
@@ -40,25 +42,23 @@ import { Circuit } from 'mollitia';
 
 ## Usage
 
-<!-- TODO change -->
 ``` javascript
-const myCircuit = new Circuit({
-  name: 'dummy',
-  options: {
-    // Customize the circuit here
-  }
-});
-// First param is your async function
-// Other params will directly be passed to this function
-myCircuit.execute(anyAsyncFunction, param1, param2, ...);
+// Imports the library
+const { Circuit } = require('mollitia');
+// Creates a circuit
+const myCircuit = new Circuit();
+// fn(yourFunction) - execute(yourParams...)
+await circuit.fn(yourFunction).execute('dummy');
 ```
 
 ## Features
 
-<!-- TODO update -->
+The point of `Mollitia` is to get every **Resilience patterns** into one library.
+It is very similar at what does [Resilience4j](https://github.com/resilience4j/resilience4j) on **Java**, but on **Node**.
 
-- Works on Node and on browser (even **IE11**, wow).
-- Can add `timeout` to your async methods.
-- Customize your circuit with [a wide variety of options](/api/options).
+<!-- TODO change links -->
 
-<!-- TODO comparison with resilience4j -->
+- Works on Node and on browser (even **IE11**, wow).
+- Implements a wide variety of Resilience patterns, [more on that here.](http://135.39.45.156:8080)
+- Has **Method Agnostic** circuits, meaning you don't have to create one circuit per function.
+- Supports plugins, [more on that here.](http://135.39.45.156:8080)

docs/content/_sidebar.md

@@ -10,6 +10,8 @@ links:
     path: /api/circuit
   - group: Core Modules
     links:
+      - title: Fallback
+        path: /api/module/fallback
       - title: Cache
         path: /api/module/cache
       - title: Retry

docs/content/api/circuit.md

@@ -3,5 +3,3 @@ title: Mollitia - API - Circuit
 ---
 
 Circuit
-
-<!-- TODO -->

docs/content/api/create-module.md

@@ -3,5 +3,3 @@ title: Mollitia - API - Create a module
 ---
 
 Create a module
-
-<!-- TODO -->

docs/content/api/create-plugin.md

@@ -3,5 +3,3 @@ title: Mollitia - API - Create a plugin
 ---
 
 Create a plugin
-
-<!-- TODO -->

docs/content/api/module/bulkhead.md

@@ -7,4 +7,50 @@ title: Mollitia - API - Module - Bulkhead
 
 ## Usage
 
-TODO
+The `Bulkhead` module allows you to **limit** concurrent executions of your circuit.
+
+``` javascript
+// Imports needed components
+const { Circuit, Bulkhead, BulkheadOverloadError, BulkheadQueueWaitError } = require('mollitia');
+// Creates a circuit
+const circuit = new Circuit({
+  options: {
+    modules: [
+      // Creates a bulkhead module
+      new Mollitia.Bulkhead({
+        concurrentSize: 2, // Allows 2 concurrent requests, if oversizing, goes in a queue.
+        queueSize: 2, // Allows 2 requests to be in queue, if oversizing, it will be rejected with a BulkheadOverloadError.
+        maxQueueWait: 30000 // After 30 seconds waiting, a queued request will be rejected with a BulkheadQueueWaitError.
+      })
+    ]
+  }
+});
+
+// Let's say this function is running multiple times in a relatively short amount of time
+circuit.fn(myFunction).execute()
+  .then(() => {
+    // The succeed normally (directly, or has been in a queue)
+  })
+  .catch((err) => {
+    if (err instanceof BulkheadOverloadError) {
+      // When the function has been called, the concurrent methods are at maximum, and the queue is full.
+    } else if (err instanceof BulkheadQueueWaitError) {
+      // The function has been waiting too long in queue (more than 30 seconds).
+    }
+    // It failed normally (directly, or has been in a queue)
+  });
+```
+
+## Options
+
+| Name             | Description                                                        | Default |
+|:-----------------|:-------------------------------------------------------------------|:--------|
+| `concurrentSize` | The number of concurrent requests that can be running in parallel. | `10`    |
+| `queueSize`      | The number of requests that can be queued.                         | `10`    |
+| `maxQueueWait`   | The amount of time before a queued request is rejected.            | `60000` |
+
+## Events
+
+| Name       | Description                          | Params             |
+|:-----------|:-------------------------------------|:-------------------|
+| `execute`  | Called when the module is executed.  | `Mollitia.Circuit` |

docs/content/api/module/cache.md

@@ -7,4 +7,56 @@ title: Mollitia - API - Module - Cache
 
 ## Usage
 
-TODO
+The `Cache` module allows you to **cache** your results for a configurable amount of time.
+Once you call a **function**, with some **parameters**, it will check if it has been cached, if so, the function will not be called at all, and will directly resolve with the cached response.
+
+> It is important to understand that the cache works by reference!<br/>
+> That means that the cache is specificly referenced **for one function**, and **for the same parameters**.<br/>
+
+``` javascript
+// Imports needed components
+const { Circuit, Cache } = require('mollitia');
+// Creates a circuit
+const circuit = new Circuit({
+  options: {
+    modules: [
+      // Creates a cache module
+      new Cache({
+        ttl: 60000  // A cached response will be kept for 1 minute
+      })
+    ]
+  }
+});
+
+// If the result is a success, it will be cached.
+await circuit.fn(myFirstFunction).execute();
+// ...
+// If this function is called before 1 minute is ellapsed, the cached response will be returned
+await circuit.fn(myFirstFunction).execute();
+// This is a simple object
+const myObject = {
+  myFirstParam: 'myFirstValue'
+};
+// Same as before, if that's a success, the result is cached. (The params are different, so it does not return the cache from before)
+await circuit.fn(myFirstFunction).execute(myObject);
+// The objects changes
+myObject.myFirstParam = 'myFirstValuesModified';
+// Nevermind, the cache works by reference, meaning the cached result is returned.
+await circuit.fn(myFirstFunction).execute(myObject);
+// That won't return the cached result, as the function is different
+await circuit.fn(mySecondFunction).execute(myObject);
+// ... After 1 minute, the function is called again.
+await circuit.fn(myFirstFunction).execute(myObject);
+```
+
+## Options
+
+| Name   | Description                                           | Default    |
+|:-------|:------------------------------------------------------|:-----------|
+| `ttl`  | The amount of time before a cached result is cleared. | `Infinity` |
+
+## Events
+
+| Name       | Description                         | Params             |
+|:-----------|:------------------------------------|:-------------------|
+| `execute`  | Called when the module is executed. | `Mollitia.Circuit` |

docs/content/api/module/fallback.md

@@ -0,0 +1,56 @@
+---
+title: Mollitia - API - Module - Fallback
+---
+# Fallback
+
+## Usage
+
+The `Fallback` module allows you to **filter** your errors.
+
+Works very well in conjunction with other modules!
+For example, filtering `Circuit Breaker` errors to return a generic error.
+
+``` javascript
+// Imports needed components
+const { Circuit, Fallback } = require('mollitia');
+// Creates a circuit
+const circuit = new Circuit({
+  options: {
+    modules: [
+      // Creates a fallback module
+      new Mollitia.Fallback({
+        cb (err) {
+          // Every time the method rejects, You can filter here
+          if (err instanceof MyError) {
+            // I know this error
+            return err; 
+          }
+          return new UnknownError();
+        }
+      })
+    ]
+  }
+});
+
+// The rejected errors are filtered, meaning you always know what is returned here
+circuit.fn(myFunction).execute()
+  .catch((err) => {
+    if (err instanceof MyError) {
+      // It's a MyError error
+    } else {
+      // It's an UnknownError error
+    }
+  });
+```
+
+## Options
+
+| Name | Description                                    | Default           |
+|:-----|:-----------------------------------------------|:------------------|
+| `cb` | The callback, called when the circuit rejects. | `Function(Error)` |
+
+## Events
+
+| Name       | Description                         | Params             |
+|:-----------|:------------------------------------|:-------------------|
+| `execute`  | Called when the module is executed. | `Mollitia.Circuit` |

docs/content/api/module/retry.md

@@ -7,4 +7,5 @@ title: Mollitia - API - Module - Retry
 
 ## Usage
 
-TODO
+* TODO add retryInterval number
+* TODO add filterRetry function to filter errors, choose to retry, and change the retryInterval

docs/content/api/module/timeout.md

@@ -7,4 +7,45 @@ title: Mollitia - API - Module - Timeout
 
 ## Usage
 
-TODO
+The `Timeout` module allows you to **ignore** the result of your async method if it takes too long.
+
+``` javascript
+// Imports needed components
+const { Circuit, Timeout, TimeoutError } = require('mollitia');
+// Creates a circuit
+const circuit = new Circuit({
+  options: {
+    modules: [
+      // Creates a timeout module
+      new Timeout({
+        delay: 120000  // Will get rejected with a TimeoutError if it takes more than 2 minutes
+      })
+    ]
+  }
+});
+
+// Let's see what happens if we run a long function
+circuit.fn(myLongFunction).execute()
+  .then(() => {
+    // It took less than 2 minutes, and succeed.
+  })
+  .catch((err) => {
+    if (err instanceof TimeoutError) {
+      // It took more than 2 minutes.
+    }
+    // It took less than 2 minutes, and failed.
+  });
+```
+
+## Options
+
+| Name     | Description                                          | Default |
+|:---------|:------------------------------------------------ ----|:--------|
+| `delay`  | The amount of time before a the promise is rejected. | `60000` |
+
+## Events
+
+| Name       | Description                          | Params             |
+|:-----------|:-------------------------------------|:-------------------|
+| `execute`  | Called when the module is executed.  | `Mollitia.Circuit` |
+| `timeout`  | Called when the module is times out. | `Mollitia.Circuit` |

docs/content/api/plugin/prometheus.md

@@ -3,5 +3,3 @@ title: Mollitia - API - Plugin - Prometheus
 ---
 
 Prometheus
-
-<!-- TODO -->

docs/content/community/modules.md

@@ -3,5 +3,3 @@ title: Mollitia - Community - Modules
 ---
 
 Modules
-
-<!-- TODO -->

docs/content/community/plugins.md

@@ -3,5 +3,3 @@ title: Mollitia - Community - Plugins
 ---
 
 Plugins
-
-<!-- TODO -->