docs: Document options.cache (#370)

closes #351

docs/index.html

@@ -854,6 +854,25 @@ <h3 class='fl m0' id='circuitbreaker'>
 
 
 
+                <tr>
+  <td class='break-word'><span class='code bold'>options.cache</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code>
+  </td>
+  <td class='break-word'><span>whether the return value of the first
+successful execution of the circuit's function will be cached. Once a value
+has been cached that value will be returned for every subsequent execution:
+the cache can be cleared using 
+<code>clearCache</code>
+. (The metrics 
+<code>cacheHit</code>
+ and
+
+<code>cacheMiss</code>
+ reflect cache activity.) Default: false
+</span></td>
+</tr>
+
+
+
             </tbody>
           </table>
 

docs/opossum.md

@@ -104,6 +104,11 @@ Constructs a [CircuitBreaker][1].
         this function returns truthy, the circuit's failPure statistics will not be
         incremented. This is useful, for example, when you don't want HTTP 404 to
         trip the circuit, but still want to handle it as a failure case.
+    -   `options.cache` **[boolean][50]** whether the return value of the first
+        successful execution of the circuit's function will be cached. Once a value
+        has been cached that value will be returned for every subsequent execution:
+        the cache can be cleared using `clearCache`. (The metrics `cacheHit` and
+        `cacheMiss` reflect cache activity.) Default: false
 
 ### close
 

lib/circuit.js

@@ -74,6 +74,12 @@ Please use options.errorThresholdPercentage`;
  * this function returns truthy, the circuit's failPure statistics will not be
  * incremented. This is useful, for example, when you don't want HTTP 404 to
  * trip the circuit, but still want to handle it as a failure case.
+ * @param {boolean} options.cache whether the return value of the first
+ * successful execution of the circuit's function will be cached. Once a value
+ * has been cached that value will be returned for every subsequent execution:
+ * the cache can be cleared using `clearCache`. (The metrics `cacheHit` and
+ * `cacheMiss` reflect cache activity.) Default: false
+ *
  *
  * @fires CircuitBreaker#halfOpen
  * @fires CircuitBreaker#close