Skip to content

Commit e1275fd

Browse files
KevinAstKevinAst
authored
Merge pull request #8 from KevinAst/feature-gitbookDoc
publish: v1.0.0 Revised Documentation
2 parents dc0f00a + 75a6ed9 commit e1275fd

35 files changed

+661
-292
lines changed

‎.gitignore

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,12 @@
66
/lib/
77
/es/
88

9-
# documentation (generated via "npm run docs")
10-
/docs/
9+
# documentation (machine generated from GitBook)
10+
/_book/
11+
12+
# api documentation (machine generated from jsdoc2md)
13+
# ... hmmm: cannot ignore it (even though it is machine generated), because gitbook ignores it too :-(
14+
# /docs/api.md
1115

1216
# code coverage reports
1317
/.nyc_output/

‎SCRIPTS.md

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,8 +90,20 @@ pkgReview ... show outdated installed packages
9090
DOCUMENTATION
9191
=============
9292
93-
docs ......... build docs from JavaDoc comments (src/*.js), and Dev Guide (src/docs)
94-
docs:clean ... clean the machine-generated docs/ directory
93+
docs ... build docs - integrating Dev Guide (GitBook: docs/*) with API (JSDoc comments: src/*.js)
94+
95+
docs:api ....... generate docs/api.md from embedded JSDoc comments in src/*.js (run as needed)
96+
97+
docs:prepare ... install gitbook/plugins/dependencies (run once and whenever a plugin is added)
98+
docs:build ..... alias to docs script (minus docs:prepare)
99+
docs:serve ..... build/serve docs (http://localhost:4000/), continuously watching for changes
100+
101+
docs:jsdoc2md:help ... show jsdoc2md command-line help (convenience)
102+
docs:gitbook:help .... show GitBook command-line help (convenience)
103+
104+
docs:clean ... clean the machine-generated docs (_book/)
105+
106+
95107
96108
97109
MISC

‎book.json

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{
2+
"gitbook": "3.2.2",
3+
"root": "./docs",
4+
"title": "astx-redux-util",
5+
"description": "Redux Reducer Composition Utilities",
6+
"author": "Kevin J. Bridges <kevinast@gmail.com> (https://github.com/KevinAst)",
7+
"structure": {
8+
"readme": "intro.md",
9+
"summary": "toc.md"
10+
},
11+
"plugins": ["-sharing", "-livereload", "toolbar"],
12+
"pluginsConfig": {
13+
"toolbar": {
14+
"buttons": [
15+
{
16+
"label": "GitHub",
17+
"icon": "fa fa-github",
18+
"url": "https://github.com/KevinAst/astx-redux-util"
19+
},
20+
{
21+
"label": "NPM",
22+
"icon": "fa fa-bullseye",
23+
"url": "https://www.npmjs.com/package/astx-redux-util"
24+
}
25+
]
26+
}
27+
},
28+
"variables": {
29+
30+
"guide": {
31+
"devGuide": "[**Dev Guide**](/index.html)",
32+
33+
"conceptConditional": "[`Conditional Reduction`](/concepts/conditionalReducer.md)",
34+
"conceptJoin": "[`Joining Reducers`](/concepts/joinReducers.md)",
35+
"concepts": "[`Concepts`](/concepts/README.md)",
36+
"conceptHash": "[`Basics`](/concepts/reducerHash.md)",
37+
38+
"dist": "[`Distribution`](/dist.md)",
39+
40+
"ext": "[`Extending astx-redux-util`](/extending/ext.md)",
41+
"logExt": "[`Logging Extension`](/extending/logExt.md)",
42+
43+
"fullExample": "[`A Most Excellent Example`](/fullExample.md)",
44+
"history": "[`Revision History`](/history.md)",
45+
"LICENSE": "[`MIT License`](/LICENSE.md)",
46+
"originalReducerState": "[`originalReducerState`](/originalReducerState.md)",
47+
"start": "[`Getting Started`](/start.md)",
48+
"why": "[`Why astx-redux-util?`](/why.md)"
49+
},
50+
51+
"api": {
52+
"ref": "[`API Reference`](/api.md)",
53+
"conditionalReducer": "[`conditionalReducer()`](/api.md#conditionalReducer)",
54+
"conditionalReducerCB": "[`conditionalReducerCB()`](/api.md#conditionalReducerCB)",
55+
"joinReducers": "[`joinReducers()`](/api.md#joinReducers)",
56+
"reducerHash": "[`reducerHash()`](/api.md#reducerHash)",
57+
"InitialState": "[`InitialState`](/api.md#InitialState)"
58+
}
59+
}
60+
}

‎src/docs/guide/LICENSE.md renamed to ‎docs/LICENSE.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# MIT License
2+
13
MIT License
24

35
Copyright (c) 2017 Kevin Bridges

‎docs/api.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
2+
<br/><br/><br/>
3+
4+
<a id="conditionalReducer"></a>
5+
6+
<h5 style="margin: 10px 0px; border-width: 5px 0px; padding: 5px; border-style: solid;">
7+
conditionalReducer(conditionalFn, thenReducerFn, [elseReducerFn], [initialState]) ⇒ [`reducerFn`](#reducerFn)</h5>
8+
Create a higher-order reducer that conditionally executes one ofthe supplied reducerFns, based on the conditionalFn() returndirective.The {{book.guide.devGuide}} discusses conditionalReducer() in more detail(see {{book.guide.conceptConditional}}), and additional examples canbe found in {{book.guide.conceptJoin}} and {{book.guide.fullExample}}.
9+
10+
11+
| Param | Type | Default | Description |
12+
| --- | --- | --- | --- |
13+
| conditionalFn | [`conditionalReducerCB`](#conditionalReducerCB) | | a callback function whose return value determines which reducerFn is executed ... truthy: thenReducerFn(), falsy: elseReducerFn(). |
14+
| thenReducerFn | [`reducerFn`](#reducerFn) | | the "wrapped" reducer invoked when conditionalFn returns truthy. |
15+
| [elseReducerFn] | [`reducerFn`](#reducerFn) | <code>identity</code> | the optional "wrapped" reducer invoked when conditionalFn returns falsy. DEFAULT: [identity function](https://lodash.com/docs#identity) |
16+
| [initialState] | [`InitialState`](#InitialState) | | the optional fall-back state value used during the state initialization boot-strap process. |
17+
18+
**Returns**: [`reducerFn`](#reducerFn) - a newly created reducer function (described above).
19+
20+
<br/><br/><br/>
21+
22+
<a id="joinReducers"></a>
23+
24+
<h5 style="margin: 10px 0px; border-width: 5px 0px; padding: 5px; border-style: solid;">
25+
joinReducers(...reducerFns, [initialState]) ⇒ [`reducerFn`](#reducerFn)</h5>
26+
Create a higher-order reducer by combining two or more reducers,logically executing each in sequence (in essence combining theirfunctionality into one). This is useful when combining variousreducer types into one logical construct.**Please Note:** Because each reducer is able to build on what hasbeen accomplished by a prior reducer, joinReducers cumulativelypasses the state parameter that was returned from any prior reducer(in the chain of reducers to execute). In essence this is anaccumulative process. While this does NOT relax the immutableconstraint of the reducer's state parameter, it is possible for adown-stream reducer to receive a state parameter that is adifferent instance from the start of the reduction process (becausean up-stream reducer needed to alter it in some way).The {{book.guide.devGuide}} discusses joinReducers() in more detail(see {{book.guide.conceptJoin}}), and additional examples canbe found in {{book.guide.fullExample}}.
27+
28+
29+
| Param | Type | Description |
30+
| --- | --- | --- |
31+
| ...reducerFns | [`reducerFn`](#reducerFn) | two or more reducer functions to join together. |
32+
| [initialState] | [`InitialState`](#InitialState) | the optional fall-back state value used during the state initialization boot-strap process. |
33+
34+
**Returns**: [`reducerFn`](#reducerFn) - a newly created reducer function (described above).
35+
36+
<br/><br/><br/>
37+
38+
<a id="reducerHash"></a>
39+
40+
<h5 style="margin: 10px 0px; border-width: 5px 0px; padding: 5px; border-style: solid;">
41+
reducerHash(actionHandlers, [initialState]) ⇒ [`reducerFn`](#reducerFn)</h5>
42+
Create a higher-order reducer by combining a set of sub-reducerfunctions that are indexed by the standard action.type. When noaction.type is acted on, the original state is merelypassed-through (using the [identityfunction](https://lodash.com/docs#identity)).This is one of the more prevalent composition reducers, andprovides an alternative to the switch statement (commonly used toprovide this control mechanism).The {{book.guide.devGuide}} discusses reducerHash() in more detail (see{{book.guide.conceptHash}}), and additional examples can be found in{{book.guide.conceptJoin}} and {{book.guide.fullExample}}.**SideBar**: Because reducerHash is so central to the rudimentaryaspect of reduction, it is a common practice to extend it,promoting a [`centralized reducer-based logging capability`](/extending/logExt.md), with an ability to correlate logging levels to state changes*(providing a means to filter logs at a high level with minimaloutput)*.
43+
44+
45+
| Param | Type | Description |
46+
| --- | --- | --- |
47+
| actionHandlers | [`ActionReducerHash`](#ActionReducerHash) | a hash of reducer functions, indexed by the standard redux action.type. |
48+
| [initialState] | [`InitialState`](#InitialState) | the optional fall-back state value used during the state initialization boot-strap process. |
49+
50+
**Returns**: [`reducerFn`](#reducerFn) - a newly created reducer function (described above).
51+
52+
<br/><br/><br/>
53+
54+
<a id="conditionalReducerCB"></a>
55+
56+
<h5 style="margin: 10px 0px; border-width: 5px 0px; padding: 5px; border-style: solid;">
57+
conditionalReducerCB ⇒ truthy</h5>
58+
A callback function (used in {{book.api.conditionalReducer}}) whosereturn value determines which reducerFn is executed.
59+
60+
61+
| Param | Type | Description |
62+
| --- | --- | --- |
63+
| state | \* | The current immutable state that is the reduction target. |
64+
| action | [`Action`](#Action) | The standard redux Action object that drives the reduction process. |
65+
| originalReducerState | \* | The immutable state at the time of the start of the reduction process. This is useful in determining whether state has changed within a series of reductions {{book.api.joinReducers}} ... because each individual reducer only has visibility of the state within it's own reduction process. Further information can be found in the {{book.guide.originalReducerState}} discussion of the {{book.guide.devGuide}}. |
66+
67+
**Returns**: truthy - A truthy value indicating which reducerFn isexecuted ... truthy: thenReducerFn(), falsy: elseReducerFn().
68+
69+
<br/><br/><br/>
70+
71+
<a id="ActionReducerHash"></a>
72+
73+
<h5 style="margin: 10px 0px; border-width: 5px 0px; padding: 5px; border-style: solid;">
74+
ActionReducerHash : Object</h5>
75+
A hash of reducer functions, indexed by the standard reduxaction.type.
76+
77+
**Properties**
78+
79+
| Name | Type | Description |
80+
| --- | --- | --- |
81+
| actionType1 | [`reducerFn`](#reducerFn) | The reducer function servicing: 'actionType1'. |
82+
| actionType2 | [`reducerFn`](#reducerFn) | The reducer function servicing: 'actionType2'. |
83+
| ...more | [`reducerFn`](#reducerFn) | ...etc. |
84+
85+
86+
<br/><br/><br/>
87+
88+
<a id="reducerFn"></a>
89+
90+
<h5 style="margin: 10px 0px; border-width: 5px 0px; padding: 5px; border-style: solid;">
91+
reducerFn ⇒ \*</h5>
92+
A standard [redux reducer function](http://redux.js.org/docs/basics/Reducers.html)that is responsible for state changes.
93+
94+
95+
| Param | Type | Description |
96+
| --- | --- | --- |
97+
| state | \* | The current immutable state that is the reduction target. |
98+
| action | [`Action`](#Action) | The standard redux action which drives the reduction process. |
99+
100+
**Returns**: \* - The resulting state after reduction.
101+
102+
<br/><br/><br/>
103+
104+
<a id="Action"></a>
105+
106+
<h5 style="margin: 10px 0px; border-width: 5px 0px; padding: 5px; border-style: solid;">
107+
Action : Object</h5>
108+
A standard [redux Action object](http://redux.js.org/docs/basics/Actions.html)that drives the reduction process.
109+
110+
**Properties**
111+
112+
| Name | Type | Description |
113+
| --- | --- | --- |
114+
| type | string | The action type. |
115+
| whatever | \* | Additional app-specific payload (as needed). |
116+
117+
118+
<br/><br/><br/>
119+
120+
<a id="InitialState"></a>
121+
122+
<h5 style="margin: 10px 0px; border-width: 5px 0px; padding: 5px; border-style: solid;">
123+
InitialState : \*</h5>
124+
All astx-redux-util reducer creators, expose an `initialState`parameter which optionally provides a fall-back state value to useduring the state initialization boot-strap process.In general, redux expects your state to have concrete values(i.e. something other than `undefined`). This means that thereduction entry point to each state element should define adefault. Keeping this in mind, the `initialState` parameter isoptional, because some reducers are "by design" (when combined in acomposition) intended to be mid-stream processors (i.e. NOT thereduction entry point).
125+

‎docs/concepts/README.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Concepts
2+
3+
- {{book.guide.conceptHash}} ... using {{book.api.reducerHash}}, eliminate
4+
the switch statement commonly found in reducers *("look ma, no
5+
switch")*
6+
7+
- {{book.guide.conceptConditional}} ... using
8+
{{book.api.conditionalReducer}}, invoke a reducer only when
9+
certain constraints are met *("to reduce or NOT to reduce; that is
10+
the question")*
11+
12+
- {{book.guide.conceptJoin}} ... using {{book.api.joinReducers}}, team up
13+
multiple reducers to promote higher order functionality *("working
14+
together is success" - Henry Ford)*

‎src/docs/guide/conceptConditional.md renamed to ‎docs/concepts/conditionalReducer.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
1+
# Conditional Reduction
2+
13
There are times where you may wish to conditionally apply a reduction.
24

35
There can be many reasons for this. Take a simple example where you
46
wish to bypass a reduction process upon determination that an action
57
will not impact an entire branch of your state tree. In this example
68
the conditional aspect is purely an optimization.
79

8-
This can be accomplished through the {@link conditionalReducer} utility.
10+
This can be accomplished through the {{book.api.conditionalReducer}} utility.
911

1012
```js
1113
import * as Redux from 'redux';
@@ -30,17 +32,17 @@ example, our action types are organized with a federated namespace, so
3032
it is easy to isolate which actions will impact various parts of our
3133
state.
3234

33-
**Please Note** that a `{}` {@link InitialState} value is applied in
35+
**Please Note** that a `{}` {{book.api.InitialState}} value is applied in
3436
this reduction, which provides the fall-back state value during the
3537
state initialization boot-strap process.
3638

3739
**Also Note:** that normally it is not necessary to supply the
38-
`elseReducerFn` {@link conditionalReducer} parameter (the third),
40+
`elseReducerFn` {{book.api.conditionalReducer}} parameter (the third),
3941
because it defaults to the [identity
4042
function](https://lodash.com/docs#identity) function, which retains
4143
the state for a falsy directive. In this case however, we had to
4244
manually pass the identity function, in order to supply the subsequent
43-
{@link InitialState} parameter.
45+
{{book.api.InitialState}} parameter.
4446

4547
**More to Come:** This example is merely intended to introduce you to
4648
the concept of conditional reduction. It is somewhat "contrived",

‎src/docs/guide/conceptJoin.md renamed to ‎docs/concepts/joinReducers.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Joining Reducers
2+
13
Occasionally it is necessary for a state to have multiple reductions
24
applied to it. Typically this occurs when the reducers involved
35
represent fundamentally different operational types.
@@ -86,8 +88,8 @@ export default function widget(widget=null, action) {
8688

8789
A more elegant solution can be accomplished by employing reducer
8890
composition, eliminating the procedural code completely. We have
89-
already discussed {@link reducerHash} and {@link conditionalReducer}.
90-
A third utility, the {@link joinReducers} function, combines two or
91+
already discussed {{book.api.reducerHash}} and {{book.api.conditionalReducer}}.
92+
A third utility, the {{book.api.joinReducers}} function, combines two or
9193
more reducers logically executing each in sequence.
9294

9395
*The following snippet, is equivalent to the one above:*

‎src/docs/guide/conceptHash.md renamed to ‎docs/concepts/reducerHash.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Basics
2+
13
Reducers frequently reason about the action.type, very often using a
24
switch statement to drive conditional logic:
35

@@ -18,7 +20,7 @@ export default function widget(widget=null, action) {
1820
}
1921
```
2022

21-
The {@link reducerHash} function *(the most common composition
23+
The {{book.api.reducerHash}} function *(the most common composition
2224
reducer)* provides a more elegant solution, eliminating the switch
2325
statement altogether. It creates a higher-order reducer, by combining
2426
a set of sub-reducer functions that are indexed by the standard
@@ -31,18 +33,21 @@ import { reducerHash } from 'astx-redux-util';
3133
export default reducerHash({
3234
"widget.edit": (widget, action) => action.widget,
3335
"widget.edit.close": (widget, action) => null,
34-
}, null);
36+
}, null); // initialState
3537
```
3638

3739
Not only is the conditional logic better encapsulated, but the default
3840
pass-through logic is automatically applied (using the [identity
3941
function](https://lodash.com/docs#identity)), passing through the
4042
original state when no action.type is acted on.
4143

42-
**Please Note** that a `null` {@link InitialState} value is applied in
44+
**Please Note** A `null` {{book.api.InitialState}} value is applied in
4345
this reduction, which provides the fall-back state value during the
4446
state initialization boot-strap process.
4547

46-
**Also Note** that because {@link reducerHash} is so central to the
48+
**SideBar** Because {{book.api.reducerHash}} is so central to the
4749
rudimentary aspects of reduction, it is common to provide a
48-
value-added {@tutorial logExt}.
50+
value-added {{book.guide.logExt}}, with the ability to correlate
51+
logging levels to state changes *(providing a means to filter logs at
52+
a high level with minimal output)*.
53+

‎src/docs/guide/dist.md renamed to ‎docs/dist.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Distribution
2+
13
This utility is primarily distributed as an [npm
24
package](https://www.npmjs.com/package/astx-redux-util) (*simply `npm
35
install` and use it in your [Node.js](https://nodejs.org/en/)

0 commit comments

Comments
 (0)