doc: document semaphore-locked and options.capacity

README.md

@@ -150,6 +150,7 @@ Here are the events you can listen for.
 * `close` - emitted when the breaker state changes to `closed`
 * `halfOpen` - emitted when the breaker state changes to `halfOpen`
 * `fallback` - emitted when the breaker has a fallback function and executes it
+* `semaphore-locked` - emitted when the breaker is at capacity and cannot execute the request
 
 Handling events gives a greater level of control over your application behavior.
 

lib/circuit.js

@@ -43,6 +43,9 @@ const CACHE = new WeakMap();
  * @param options.rollingPercentilesEnabled {boolean} This property indicates whether execution latencies
  *  should be tracked and calculated as percentiles.
  *  If they are disabled, all summary statistics (mean, percentiles) are returned as -1.
+ * @param options.capacity the number of concurrent requests allowed. If the number of
+ * currently executing function calls is equal to options.capacity, further calls to `fire()`
+ * are rejected until at least one of the current requests completes.
  */
 class CircuitBreaker extends EventEmitter {
   constructor (action, options) {