# promise-flow-extensions

> Extends the Promise object with some additional utility functions

Latest version **2.0.0** (published 2016-08-31) · ISC license · 0 weekly downloads

## Install

```sh
npm install promise-flow-extensions
pnpm add promise-flow-extensions
yarn add promise-flow-extensions
bun add promise-flow-extensions
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2016-08-31 |
| First published | 2016-06-16 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Ezequiel Rabinovich |
| Maintainers | warseph |
| Keywords | promise, extensions, helpers, utilities |

## Links

- npm: https://www.npmjs.com/package/promise-flow-extensions
- Repository: https://github.com/warseph/promise-flow-extensions
- Homepage: https://github.com/warseph/promise-flow-extensions#readme
- Issues: https://github.com/warseph/promise-flow-extensions/issues
- npm.io page: https://npm.io/package/promise-flow-extensions

## Dependencies (1)

- [library-extensions](https://npm.io/package/library-extensions.md) ^1.1.0

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2016-08-31
- 1.1.1 — 2016-08-30
- 1.1.0 — 2016-08-30
- 1.0.1 — 2016-06-18
- 1.0.0 — 2016-06-16

## README

# Promise Flow Extensions

This are simple extensions to make handling some common promise flows a bit
more simple.

# Instalation:

```
$ npm install --save promise-flow-extensions
```

# Usage

The library can be used in three ways
### Directly accessing the helper methods:
```js
const promiseFlowExt = require('promise-flow-extensions');

promiseFlowExt.if(Promise.resolve(2), {condition: v => v > 1, true: v => v - 1})
  .then(console.log); // 1
```
**Important!** when using functions this way, the first parameter is always the
promise
### Extending a specific promise:
```js
const promiseFlowExt = require('promise-flow-extensions');

const eventually2 = Promise.resolve(2);
promiseFlowExt.extend(eventually2);
eventually2.if({condition: v => v > 1, true: v => v - 1})
  .then(console.log); // 1
```
### Extending all promises
```js
const promiseFlowExt = require('promise-flow-extensions');
promiseFlowExt.extend(Promise.prototype);

const eventually2 = Promise.resolve(2);
eventually2.if({condition: v => v > 1, true: v => v - 1})
  .then(console.log); // 1
```

### Removing the extensions
You can reset an extended object (i.e. remove all the added methods) by running
```js
const promiseFlowExt = require('promise-flow-extensions');
promiseFlowExt.extend(Promise.prototype);
promiseFlowExt.reset(Promise.prototype);

const promise = Promise.resolve(1);
promise.rethrow(() => null) // promise.rethrow is not a function
  .then(console.log);
```

# Methods

All methods can be called using the 3 options shown above, we'll assume we have
extended all promises for all examples.

## `rethrow(function)`
Catches and exception and executes the passed function. Then it rethrows the
exception received. The function receives the thrown error as an argument.
```js
Promise.reject(new Error('test'))
  .rethrow(e => console.log(e.message)) // test
  .then(v => 'this is never called')
  .catch(e => /* actually handle the error */);
```

## `if(trueFn | {condition, true, false})`
Executes the passed function if the promise is true.
Instead of a function you can provide an object, specify up to 3 values, if any
of those values isn't specified, the default is the identity function, i.e.
`v => v`
  - condition: a function that will be used to evaluate if the promise result
    is true/false
  - true: The function that will be executed when the condition is true
  - false: The function that will be executed when the condition is false
```js
Promise.resolve('test')
  .if({
    condition: v => v === 'test',
    true: v => v + ' ok!',
    false: v => 'this is never called'
  }) // 'test ok!'
  .then(console.log); // 'test ok!'
```

## `retry(function, [condition, [options]])`
Executes the passed function. It will check the result (or the result of calling
condition with the result if a condition is provided). If it's false it will
retry the function `options.retries` times (default: 1), waiting
`options.interval` milliseconds (default 1000) between retries.

`option.interval` is a function, that is called each time with the number of
retries remaining.

If retries run out it will reject the promise with an exception.
```js
Promise.resolve('http://example.org/my-simple-service')
  .retry(u => callService(u), r => r.body === 'ok', {
    retries: 10,
    interval: retries => (10 - retries) * 1000
  })
  .catch(e => {body: 'failed'})
  .then(console.log); // something like {body: ok} ok {body: 'failed'}
```

---
_Source: https://npm.io/package/promise-flow-extensions · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._