# action-to-promise

> Utility converting action to Promise in redux-saga environment.

Latest version **1.4.4** (published 2020-06-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install action-to-promise
pnpm add action-to-promise
yarn add action-to-promise
bun add action-to-promise
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.4 |
| Published | 2020-06-12 |
| First published | 2019-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 116.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Dariusz Dziara |
| Maintainers | ddziara |
| Keywords | action, promise, redux-saga, saga, convert, transform |

## Links

- npm: https://www.npmjs.com/package/action-to-promise
- Repository: https://github.com/ddziara/node-action-to-promise
- Homepage: https://github.com/ddziara/node-action-to-promise#readme
- Issues: https://github.com/ddziara/node-action-to-promise/issues
- npm.io page: https://npm.io/package/action-to-promise

## Dependencies (3)

- [redux](https://npm.io/package/redux.md) ^4.0.5
- [handlebars](https://npm.io/package/handlebars.md) >=4.3.0
- [redux-saga](https://npm.io/package/redux-saga.md) ^1.1.3

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.4.4 (latest) — 2020-06-12
- 1.4.3 — 2020-02-25
- 1.4.2 — 2020-02-20
- 1.4.1 — 2020-02-20
- 1.4.0 — 2020-02-20
- 1.3.0 — 2019-10-21
- 1.2.1 — 2019-10-04
- 1.2.0 — 2019-10-03
- 1.1.7 — 2019-09-24
- 1.1.6 — 2019-09-23
- 1.1.5 — 2019-09-23
- 1.1.4 — 2019-09-23
- 1.1.3 — 2019-09-23
- 1.1.2 — 2019-09-23
- 1.1.1 — 2019-09-23

## README

# action-to-promise
Utility converting action to Promise in redux-saga environment

# What it does
It dispatches modified redux action to a store using helper function which in turn returns a Promise which will be resolved 
or rejected when corresponding associated action either on success or error will be PUT-ted by redux-saga.

# How it works
Function 
```javascript
dispatchStartAction(store: Store, action: AnyAction) => Promise<void> 
```
creates a new action and dispatches it to redux store
```javascript
{ 
    type: <original_action_type>, 
    resolve: <promise_executor_resolve>, 
    reject: <promise_executor_reject>, 
    payload: <original_action> 
}
```
where **payload** property contains original action, **type** property repeats original action type and **resolve**, **reject** properties 
were passed to the executor of the returned Promise.

Then SagaMonitor object intercepts and traces saga effects using unique identifiers & parent-child relations. 
When either success or error action are dispatched (PUT) to the store then the Promise is either resolved or rejected.

# How to use it

to install:
```javascript
npm install action-to-promise
```

in code:
```javascript
import createSagaMiddleware from "redux-saga";
import { createAction2PromiseWrapper } from 'action-to-promise';

...
// creating redux store
const action2PromiseWrapper = createAction2PromiseWrapper(createSagaMiddleware);  // pass Saga createSagaMiddleware function as parameter

// register observed action types: start_action_type, resolve_action_type, reject_action_type
action2PromiseWrapper.registerActions({ start: start_action_type1, resolve: resolve_action_type1, reject: reject_action_type1 });
action2PromiseWrapper.registerActions({ start: start_action_type2, resolve: resolve_action_type2, reject: reject_action_type2 });
...

// use wrapper function to call original Saga createSagaMiddleware()
const initialiseSagaMiddleware = action2PromiseWrapper.createSagaMiddleware();

export const store = createStore(reducerRoot, storeEnhancers(applyMiddleware(initialiseSagaMiddleware)));

initialiseSagaMiddleware.run(watcherSaga);
```

```javascript
// dispatching action transformed to Promise
import { dispatchStartAction } from 'action-to-promise';
import { store } from '../redux/store';

...
function loadMoreRows(limit, offset) {
    return dispatchStartAction(store, start_action_creator(limit, offset));
}
...
```

# Handled Saga scenarios
```javascript
// common worker Saga
function* workerSaga(action) {
    try {
        ...
        yield put(resolve_action);
    } catch (e) {
        yield put(reject_action);
    }
}
```

```javascript
// action channel is used and then FORK effect
function* watcherSaga() {
    const actChan = yield actionChannel(start_action_type);

    while (true) {
        const action = yield take(actChan);
        const org_action = actionFromPromiseAction(action);  <=== important: function restores original action
        yield fork(workerSaga, org_action);
    }
}
```

```javascript
// actions are retrieved directly then FORK effect is used
function* watcher() {
    while (true) {
        const action = yield take(start_action_type);
        const org_action = actionFromPromiseAction(action);  <=== important: function restores original action
        yield fork(workerSaga, org_action);
    }
}
```

```javascript
// action channel is used and then CALL effect
function* watcherSaga() {
    const actChan = yield actionChannel(start_action_type);

    while (true) {
        const action = yield take(actChan);
        const org_action = actionFromPromiseAction(action);  <=== important: function restores original action
        yield call(workerSaga, org_action);
    }
}
```

```javascript
// actions are retrieved directly then CALL effect is used
function* watcherSaga() {
    while (true) {
        const action = yield take(start_action_type);
        const org_action = actionFromPromiseAction(action);  <=== important: function restores original action
        yield call(workerSaga, org_action);
    }
}
```

# API

```javascript
export interface IActionTriple {
    start: string;
    resolve: string;
    reject: string;
}

interface IAction2PromiseWrapper {
    createSagaMiddleware: (options?: any) => any; 
    registerActions: (actions: IActionTriple) => void; 
    dispatchStartAction: (store: Store, action: AnyAction) => Promise<void>;
    compDispatchStartAction: (dispatch: (action: AnyAction) => AnyAction, action: AnyAction) => Promise<void>;
}  
```

#### `function createAction2PromiseWrapper(orgCreateSagaMiddleware: any): IAction2PromiseWrapper`

Function creates main object with helper methods as properties. These methods are used to register observed actions 
and to create wrapper Saga `createSagaMiddleware` function.

#### `<action2promisewrapper>.registerActions(actions: IActionTriple) => void`

Function registers triple of associated action types:
* start - action type that begins the sequence
* resolve - action type that resolves the Promise
* reject - action type that rejects the Promise

#### `<action2promisewrapper>.createSagaMiddleware(options?: any) => any`

Function calls original Saga createSagaMiddleware with own `options` object. It supplies `effectTriggered`. `effectResolved`,
`effectRejected`, `effectCancelled`, `actionDispatched` handlers that finally call original methods if any passed as properties 
of `options`.

```javascript
interface IA2PAction {
    type: string;
    resolve: any;
    reject: any
    payload: AnyAction;
}
```

#### `<action2promisewrapper>.dispatchStartAction(store: Store, action: AnyAction) => Promise<void>`

Function dispatches action to the store calling 'dispatch' method of the store. It returns promise that will be resolved or rejected
depending on action (either resolve or reject) PUT'ed to the store.
Note: this method throws an exception if `action` type is not registered

#### `<action2promisewrapper>.compDispatchStartAction(dispatch: (action: AnyAction) => AnyAction, action: AnyAction) => Promise<void>`

Function dispatches action to store calling 'dispatch' method bound to that store. It returns promise that will be resolved or rejected
depending on action (either resolve or reject) PUT'ed to the store.
Note: this method throws an exception if `action` type is not registered

#### `dispatchStartAction(store: Store, action: AnyAction) => Promise<void>`

Function dispatches action to the store calling 'dispatch' method of the store. It returns promise that will be resolved or rejected
depending on action (either resolve or reject) PUT'ed to the store.
Note: this function is deprecated, use `<action2promisewrapper>.dispatchStartAction(...)` instead

#### `compDispatchStartAction(dispatch: (action: AnyAction) => AnyAction, action: AnyAction) => Promise<void>`

Function dispatches action to store calling 'dispatch' method bound to that store. It returns promise that will be resolved or rejected
depending on action (either resolve or reject) PUT'ed to the store.
Note: this function is deprecated, use `<action2promisewrapper>.compDispatchStartAction(...)` instead

#### `actionFromPromiseAction(action: AnyAction) => AnyAction`

Function usually called in Saga generator function to restore original action without `resolve` and `reject` properties.
If `resolve` or `reject` is missing then it returns passed as parameter action.

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