action-u
Version:
Redux Action Generator (promoting action creators and types)
223 lines (163 loc) • 8.26 kB
Markdown
# action-u
The action-u library provides a utility that auto generates your
[redux] [action creators], and introduces organization to your
[actions] through a JSON-based [ActionStruct]. This structure
instinctively groups related actions, implicitly defines your action
types, and seamlessly promotes both [action creators] and action types
throughout your application. This automates a tedious process, and
promotes an overall organization to your actions.
<!--- Badges for CI Builds --->
[](https://travis-ci.org/KevinAst/action-u)
[](https://www.codacy.com/app/KevinAst/action-u?utm_source=github.com&utm_medium=referral&utm_content=KevinAst/action-u&utm_campaign=Badge_Grade)
[](https://www.codacy.com/app/KevinAst/action-u?utm_source=github.com&utm_medium=referral&utm_content=KevinAst/action-u&utm_campaign=Badge_Coverage)
[](https://snyk.io/test/github/kevinast/action-u)
[](https://www.npmjs.com/package/action-u)
## Install
```shell
npm install --save action-u
```
## Sample
As a simple example, let's say we want to facilitate an activity to
display a user message. We will need:
- an action to display the message in a dialog,
- and a corresponding action to close the dialog.
**Generation**:
By simply knowing the properties of each action, we can auto-generate
our needed [ActionStruct] as follows:
```js
import {generateActions} from 'action-u';
const actions = generateActions({
userMsg: {
display: {
actionMeta: {
traits: ['msg']
}
},
close: {
actionMeta: {}
}
}
});
```
Because our two actions are inner-related, we packaged them in an
app-specific structure that highlights these relationship through it's
shape. The `actions` [ActionStruct] *(returned above)* conceptually
looks like this:
```js
const actions = { // auto-generated (from generateActions() - above)
userMsg {
display(msg): {},
close(): {},
}
};
```
1. The **action creator** signatures are shown, but their
implementations are omitted.
- `actions.userMsg.display(msg)` is the **1st action creator**, and
accepts a single `msg` parameter
- `actions.userMsg.close()` is the **2nd action creator**, and
accepts no parameters
1. The **action types** are implied from the JSON structure, and are
promoted through a string coercion of the action creator function
itself (the function's toString() has been overloaded).
In many contexts, this coercion happens implicitly *(such as
astx-redux-util reducerHash())*, while in other cases it must be
explicitly done *(for example, the case of a switch statement)*.
```js
String(actions.userMsg.display) // yields: 'userMsg.display'
''+actions.userMsg.close // yields: 'userMsg.close'
```
**A Closer Look**
The following diagram summarizes the generation process
1. The [generateActions] function accepts a single
[ActionGenesis] parameter that:
- defines one or more action creators
- implies the action types from the JSON structure
- defines the overall [ActionStruct] organization
1. [ActionNodes] (ones that promote action creator functions) are defined
through the [actionMeta] property.
- The [actionMeta.traits] property is a string array
that defines *both* the parameter names (of the action creator)
and ultimately the property names of the action (returned from
the action creator).
- An empty [actionMeta] object (see `close`) merely defines an
action creator with NO parameters, and consequently no action
payload properties.
- There are more [actionMeta] properties that are discussed in the
full documentation.
**Formatting Preference**: So as to not confuse the [actionMeta]
property with app-level nodes, I prefer to indent them a bit deeper in
the structure *(you are free to disregard this advice)*.
1. All other nodes (like `userMsg`) are merely intermediate nodes that
organize (i.e. add meaning) to the overall shape of the action
structure.
**Usage**:
Here is how the generated [ActionStruct] *(above)* is used:
```js
// action creators ...
const userMsg = actions.userMsg.display('Hello action-u');
// yields the following action (which can be dispatched):
// {
// type: 'userMsg.display',
// msg: 'Hello action-u'
// }
const closeIt = actions.userMsg.close();
// yields the following action (which can be dispatched):
// {
// type: 'userMsg.close'
// }
// action types (typically used in reducers) ...
console.log(`First type is '${actions.userMsg.display}'`); // First type is 'userMsg.display'
console.log(`Second type is '${actions.userMsg.close}'`); // Second type is 'userMsg.close'
```
## Comprehensive Documentation
The sample above just scratches the service!
**Comprehensive Documentation** can be found at https://action-u.js.org/,
which includes both a **Dev Guide** *(building concepts with full and
thorough **examples**)*, and a complete **API Reference**.
There is much more to cover in fully understanding this utility,
including:
- [ActionStruct Shapes] ... there is a lot of flexibility in how you
organize your [ActionStruct]
- [Parameter Validation] ... learn how to inject app-specific
validation
- [Defaulting Parameters] ... learn how to apply default semantics to
your action creator parameters
- [Thunk Action Creators] ... learn how to integrate thunks into
action-u
- [Action Promotion] ... options to maintain and promote the
actions within your application
- [Action Documentation] ... considerations for documenting your
actions
- [API Reference] ... and *(of course)* the complete functional **API
Reference**
The action-u library was pulled from a sandbox project
([GeekU](https://github.com/KevinAst/GeekU)) that I use to study
several technologies and frameworks.
I hope you enjoy this effort, and comments are always welcome.
</Kevin>
[action-u]: https://action-u.js.org/
[Getting Started]: https://action-u.js.org/start.html
[Basics]: https://action-u.js.org/basics.html
[A Closer Look]: https://action-u.js.org/formalTypes.html
[ActionStruct Shapes]: https://action-u.js.org/shapes.html
[Parameter Validation]: https://action-u.js.org/validation.html
[Defaulting Parameters]: https://action-u.js.org/default.html
[Thunk Action Creators]: https://action-u.js.org/thunks.html
[Action Promotion]: https://action-u.js.org/promotion.html
[Action Documentation]: https://action-u.js.org/actionDoc.html
[Distribution]: https://action-u.js.org/dist.html
[Why action-u?]: https://action-u.js.org/why.html
[Revision History]: https://action-u.js.org/history.html
[MIT License]: https://action-u.js.org/LICENSE.html
[API Reference]: https://action-u.js.org/api.html
[generateActions]: https://action-u.js.org/api.html#generateActions
[ActionNodes]: https://action-u.js.org/api.html#ActionNodes
[ActionGenesis]: https://action-u.js.org/api.html#ActionGenesis
[actionMeta]: https://action-u.js.org/api.html#ActionMeta
[actionMeta.traits]: https://action-u.js.org/api.html#ActionMeta
[ActionStruct]: https://action-u.js.org/api.html#ActionStruct
[redux]: http://redux.js.org/
[actions]: http://redux.js.org/docs/basics/Actions.html
[action creators]: http://redux.js.org/docs/basics/Actions.html#action-creators