Renames Future.recover -> Future.orElse (#136)

annotations/source/en/concurrency/future/future/or-else.md

@@ -0,0 +1,22 @@
+@annotate: folktale.concurrency.future._Future.prototype.orElse
+category: Recovering From Errors
+---
+
+Transforms a failed future into a new future.
+
+
+## Example::
+
+    const { rejected, of } = require('folktale/concurrency/future');
+
+    of(1).orElse(x => of(x + 1)).listen({
+      onResolved: (value) => $ASSERT(value == 1)
+    });
+
+    rejected(1).orElse(x => of(x + 1)).listen({
+      onResolved: (value) => $ASSERT(value == 2)
+    });
+
+    rejected(1).orElse(x => rejected(x + 1)).listen({
+      onRejected: (value) => $ASSERT(value == 2)
+    });

packages/base/source/concurrency/future/_future.js

@@ -12,6 +12,7 @@ const define = require('folktale/helpers/define');
 const provideAliases = require('folktale/helpers/provide-fantasy-land-aliases');
 const Deferred = require('./_deferred');
 const { Pending, Resolved, Rejected } = require('./_execution-state');
+const warnDeprecation = require('folktale/helpers/warn-deprecation');
 
 
 
@@ -133,11 +134,24 @@ class Future {
 
   // ---[ Recovering from errors ]-------------------------------------
   /*~
-   * stability: experimental
+   * deprecated:
+   *   since: 2.1.0
+   *   replacedBy: .orElse(handler)
+   * 
    * type: |
    *   (Future 'f 's).(('f) => Future 'f2 's2) => Future 'f2 's
    */
   recover(handler) {
+    warnDeprecation('`.recover` was renamed to `.orElse` for consistency, and thus `.recover(handler)` is deprecated. Use `.orElse(handler)` instead.');
+    return this.orElse(handler);
+  }
+
+  /*~
+   * stability: experimental
+   * type: |
+   *   (Future 'f 's).(('f) => Future 'f2 's2) => Future 'f2 's
+   */
+  orElse(handler) {
     let deferred = new Deferred();      // eslint-disable-line prefer-const
     this.listen({
       onCancelled: ()     => deferred.cancel(),