diff --git a/annotations/source/en/concurrency/future/future/or-else.md b/annotations/source/en/concurrency/future/future/or-else.md new file mode 100644 index 0000000..c784376 --- /dev/null +++ b/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) + }); diff --git a/packages/base/source/concurrency/future/_future.js b/packages/base/source/concurrency/future/_future.js index 3e9d761..d2f04bb 100644 --- a/packages/base/source/concurrency/future/_future.js +++ b/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(),