Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

redux-routine: set up autogenerated API docs #14228

Merged
merged 6 commits into from
Mar 8, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion bin/update-readmes.js
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ const packages = [
'keycodes',
//'plugins',
'priority-queue',
//'redux-routine',
'redux-routine',
'rich-text',
'shortcode',
//'url',
Expand Down
30 changes: 25 additions & 5 deletions packages/redux-routine/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,19 +57,39 @@ request has completed does the action creator procede to return the `SET_TEMPERA

## API

### `createMiddleware( controls: ?Object )`
<!-- START TOKEN(Autogenerated API docs) -->

Create a Redux middleware, given an object of controls where each key is an action type for which to act upon, the value a function which returns either a promise which is to resolve when evaluation of the action should continue, or a value. The value or resolved promise value is assigned on the return value of the yield assignment. If the control handler returns undefined, the execution is not continued.
### default

[src/index.js#L19-L30](src/index.js#L19-L30)

Creates a Redux middleware, given an object of controls where each key is an
action type for which to act upon, the value a function which returns either
a promise which is to resolve when evaluation of the action should continue,
or a value. The value or resolved promise value is assigned on the return
value of the yield assignment. If the control handler returns undefined, the
execution is not continued.

**Parameters**

- **controls** `Object`: Object of control handlers.

**Returns**

`Function`: Co-routine runtime


<!-- END TOKEN(Autogenerated API docs) -->

## Motivation

`@wordpress/redux-routine` shares many of the same motivations as other similar generator-based Redux side effects solutions, including `redux-saga`. Where it differs is in being less opinionated by virtue of its minimalism. It includes no default controls, offers no tooling around splitting logic flows, and does not include any error handling out of the box. This is intended in promoting approachability to developers who seek to bring asynchronous or conditional continuation flows to their applications without a steep learning curve.

The primary motivations include, among others:

- **Testability**: Since an action creator yields plain action objects, the behavior of their resolution can be easily substituted in tests.
- **Controlled flexibility**: Control flows can be implemented without sacrificing the expressiveness and intentionality of an action type. Other solutions like thunks or promises promote ultimate flexibility, but at the expense of maintainability manifested through deep coupling between action types and incidental implementation.
- A **common domain language** for expressing data flows: Since controls are centrally defined, it requires the conscious decision on the part of a development team to decide when and how new control handlers are added.
- **Testability**: Since an action creator yields plain action objects, the behavior of their resolution can be easily substituted in tests.
- **Controlled flexibility**: Control flows can be implemented without sacrificing the expressiveness and intentionality of an action type. Other solutions like thunks or promises promote ultimate flexibility, but at the expense of maintainability manifested through deep coupling between action types and incidental implementation.
- A **common domain language** for expressing data flows: Since controls are centrally defined, it requires the conscious decision on the part of a development team to decide when and how new control handlers are added.

## Testing

Expand Down