Merge branch 'enhancer'

Author: joshburgess

Diff for: .babelrc

@@ -5,40 +5,32 @@
         ["env", {
           "modules": "commonjs"
         }],
-        "stage-3",
-        "react"
-      ],
-      "plugins": []
+        "stage-3"
+      ]
     },
     "es": {
       "presets": [
         ["env", {
           "modules": false
         }],
-        "stage-3",
-        "react"
-      ],
-      "plugins": []
+        "stage-3"
+      ]
     },
     "umd": {
       "presets": [
         ["env", {
           "modules": false
         }],
-        "stage-3",
-        "react"
-      ],
-      "plugins": []
+        "stage-3"
+      ]
     },
     "test": {
       "presets": [
         ["env", {
           "modules": "commonjs"
         }],
-        "stage-3",
-        "react"
-      ],
-      "plugins": []
+        "stage-3"
+      ]
     }
   },
   "comments": false

Diff for: README.md

@@ -73,10 +73,14 @@ programming.
 __Summary__
 
 - There are no adapters. `redux-most` is only intended to be used with `Most`.
+- `redux-most` offers 2 separate APIs: a `redux-observable`-like API, where Epics
+get passed an action stream & a store middleware object containing `dispatch` & `getState`
+methods, and a stricter, more declarative API, where Epics get passed an action stream & a state stream.
 - `combineEpics` takes in an array of epics instead of multiple arguments.
 - Standard `Most` streams are used instead of a custom Observable extension.
 - `select` and `selectArray` are available instead of the variadic `ofType`.
 
+
 __Further Elaboration:__
 
 As the name implies, `redux-most` does not offer adapters for use with other reactive
@@ -87,8 +91,23 @@ JavaScript ecosystem right now, and `Most 2.0` will be even better, as it will f
 auto-curried API like `lodash/fp` and `ramda`, but for working with streams instead of arrays.
 For a preview of what's to come, check out what's going on [here](https://github.com/mostjs/core).
 
-Whereas `comebineEpics` is variadic in `redux-observable`, it's unary in `redux-most`. It takes in
-only one argument, an array of epics, instead of individual epics getting passed in as separate
+Initially, `redux-most` offered the same API as `redux-observable`, where Epics received an action
+stream & a store middleware object containing `dispatch` & `getState` methods. However, it now offers
+both that API and another stricter, more declarative API which eliminates the use of `dispatch` &
+`getState`. The reason for this is that I rarely found myself using the imperative `dispatch`
+method. It's not really needed, because you can use `switch`, `merge`, `mergeArray`, etc. to send
+multiple actions through your outgoing stream. This is nice, because it allows you to stay locked into
+the declarative programming style the entire time.
+
+However, using `getState` was still required in epics that needed access to the current state. I
+wanted a nice, convenient way to access the current state, just like I had for dispatching actions.
+So, I created an alternate API where Epics receive a stream of state changes rather than the
+`{ dispatch, getState }` object. This state stream, combined with the new `withState` utility function,
+let's you use streams for both dispatching actions & accessing the current state, allowing you to stay 
+focused & in the zone (the reactive programming mindset).
+
+Moving on, whereas `comebineEpics` is variadic in `redux-observable`, it's unary in `redux-most`. It
+takes in only one argument, an array of epics, instead of individual epics getting passed in as separate
 arguments.
 
 As for streams, I chose not to extend the `Observable` type with a custom `ActionsObservable`
@@ -105,7 +124,7 @@ practice in functional programming to prefer a known number of arguments over a
 of arguments. Therefore, `select` is used when we want to filter by a single action type, and
 `selectArray` is used when we want to filter by multiple action types (via an array) simultaneously.
 
-Additionally, to better align with the `Most` API, and because these fucntions take a known number
+Additionally, to better align with the `Most` API, and because these functions take a known number
 of arguments, `select` & `selectArray` are curried, which allows them to be used in either a
 fluent style or a more functional style which enables the use of further currying, partial
 application, & functional composition.
@@ -161,11 +180,13 @@ const someOtherEpic = pipe(
 ## API Reference
 
 - [createEpicMiddleware](https://github.com/joshburgess/redux-most#createepicmiddleware-rootepic)
+- [createStateStreamEnhancer](https://github.com/joshburgess/redux-most#createstatestreamenhancer-epicmiddleware)
 - [combineEpics](https://github.com/joshburgess/redux-most#combineepics-epics)
 - [EpicMiddleware](https://github.com/joshburgess/redux-most#epicmiddleware)
 - [replaceEpic](https://github.com/joshburgess/redux-most#replaceEpic)
 - [select](https://github.com/joshburgess/redux-most#select-actiontype-stream)
 - [selectArray](https://github.com/joshburgess/redux-most#selectArray-actiontypes-stream)
+- [withState](https://github.com/joshburgess/redux-most#withstate-statestream-actionstream)
 
 ---
 
@@ -204,6 +225,44 @@ export default function configureStore() {
 
 ---
 
+### `createStateStreamEnhancer (epicMiddleware)`
+
+`createStateStreamEnhancer` is used to access `redux-most`'s alternate API, which passes
+`Epics` a state stream (Ex: `state$`) instead of the `{ dispatch, getState }` store
+`MiddlewareAPI` object. You must provide an instance of the `EpicMiddleware`, and the
+resulting function must be applied AFTER using `redux`'s `applyMiddleware` if also using
+other middleware.
+
+__Arguments__
+
+1. `rootEpic` _(`Epic`)_: The root Epic.
+
+__Returns__
+
+_(`MiddlewareAPI`)_: An enhanced instance of the `redux-most` middleware, exposing a stream
+of state change values.
+
+__Example__
+```js
+import { createStore, applyMiddleware } from 'redux'
+import {
+  createEpicMiddleware,
+  createStateStreamEnhancer,
+} from 'redux-most'
+import rootEpic from '../epics'
+
+const epicMiddleware = createEpicMiddleware(rootEpic)
+const middleware = [...] // other middleware here
+const storeEnhancers = compose(
+  createStateStreamEnhancer(epicMiddleware),
+  applyMiddleware(...middleware)
+)
+
+const store = createStore(rootReducer, storeEnhancers)
+```
+
+---
+
 ### `combineEpics (epicsArray)`
 
 `combineEpics`, as the name suggests, allows you to pass in an array of epics and combine them into a single one.
@@ -298,6 +357,11 @@ __Arguments__
 1. `actionType` _(`string`)_: The type of action to filter by.
 2. `stream` _(`Stream`)_: The stream of actions you are filtering. Ex: `actions$`.
 
+__Returns__
+
+_(Stream)_: A new, filtered stream holding only the actions corresponding to the action
+type passed to `select`.
+
 The `select` operator is curried, allowing you to use a fluent or functional style.
 
 __Examples__
@@ -369,6 +433,11 @@ __Arguments__
 1. `actionTypes` _(`string[]`)_: An array of action types to filter by.
 2. `stream` _(`Stream`)_: The stream of actions you are filtering. Ex: `actions$`.
 
+__Returns__
+
+_(Stream)_: A new, filtered stream holding only the actions corresponding to the action
+types passed to `selectArray`.
+
 The `selectArray` operator is curried, allowing you to use a fluent or functional style.
 
 __Examples__
@@ -447,3 +516,52 @@ const clear = compose(
 
 export default clear
 ```
+---
+
+### `withState (stateStream, actionStream)`
+
+A utility function for use with `redux-most`'s optional state stream API. This
+provides a convenient way to `sample` the latest state change value. Note:
+accessing the alternate API requires using `createStateStreamEnhancer`.
+
+__Arguments__
+
+1. `stateStream` _(`Stream`)_: The state stream provided by `redux-most`'s alternate API.
+2. `actionStream` _(`Stream`)_: The filtered stream of action events used to trigger
+sampling of the latest state. (Ex: `actions$`).
+
+__Returns__
+
+_(`[state, action]`)_: An Array of length 2 (or Tuple) containing the latest
+state value at index 0 and the latest action of the filtered action stream at index 1.
+
+`withState` is curried, allowing you to pass in the state stream & action stream
+together, at the same time, or separately, delaying passing in the action stream.
+This provides the user extra flexibility, allowing it to easily be used within 
+functional composition pipelines.
+
+__Examples__
+```js
+import { select, withState } from 'redux-most'
+import { curriedMap as map } from '../utils'
+import compose from 'ramda/src/compose'
+
+const accessStateFromArray = ([state, action]) => ({
+  type: 'ACCESS_STATE',
+  payload: {
+    latestState: state,
+    accessedByAction: action,
+  },
+})
+
+// dispatch { type: 'STATE_STREAM_TEST' } in Redux DevTools to test
+const stateStreamTest = (action$, state$) => compose(
+ map(accessStateFromArray),
+ withState(state$),
+ select('STATE_STREAM_TEST')
+)(action$)
+
+export default stateStreamTest
+```
+
+---

Diff for: examples/navigation-react-redux/.babelrc

@@ -5,6 +5,5 @@
     }],
     "stage-3",
     "react"
-  ],
-  "plugins": []
+  ]
 }

Diff for: examples/navigation-react-redux/epics/index.js

@@ -5,13 +5,15 @@ import searchUsers from './searchUsers'
 import clearSearchResults from './clearSearchResults'
 import fetchReposByUser from './fetchReposByUser'
 import adminAccess from './adminAccess'
+import stateStreamTest from './stateStreamTest'
 
 const rootEpic = combineEpics([
   searchUsersDebounced,
   searchUsers,
   clearSearchResults,
   fetchReposByUser,
   adminAccess,
+  stateStreamTest,
 ])
 
 export default rootEpic

Diff for: examples/navigation-react-redux/epics/stateStreamTest.js

@@ -0,0 +1,29 @@
+import {
+  select,
+  withState,
+} from 'redux-most'
+// import {
+//   select,
+//   withState,
+// } from '../../../src'
+import {
+  curriedMap as map,
+} from '../utils'
+import compose from 'ramda/src/compose'
+
+const accessStateFromArray = ([state, action]) => ({
+  type: 'ACCESS_STATE',
+  payload: {
+    latestState: state,
+    accessedByAction: action,
+  },
+})
+
+// dispatch { type: 'STATE_STREAM_TEST' } in Redux DevTools to test
+const stateStreamTest = (action$, state$) => compose(
+ map(accessStateFromArray),
+ withState(state$),
+ select('STATE_STREAM_TEST')
+)(action$)
+
+export default stateStreamTest

Diff for: examples/navigation-react-redux/package.json

@@ -29,18 +29,18 @@
     "react-router-redux": "^4.0.5",
     "redux": "^3.5.2",
     "redux-logger": "^3.0.6",
-    "redux-most": "^0.5.2"
+    "redux-most": "0.6.0-alpha2"
   },
   "devDependencies": {
-    "babel-cli": "^6.11.4",
-    "babel-core": "^6.11.4",
+    "babel-cli": "^6.26.0",
+    "babel-core": "^6.26.0",
     "babel-eslint": "^7.1.1",
-    "babel-loader": "^7.0.0",
-    "babel-preset-env": "^1.5.0",
+    "babel-loader": "^7.1.2",
+    "babel-preset-env": "^1.6.0",
     "babel-preset-react": "^6.24.1",
     "babel-preset-stage-3": "^6.22.0",
-    "babel-register": "^6.24.1",
-    "webpack": "^2.5.1",
+    "babel-register": "^6.26.0",
+    "webpack": "^3.5.5",
     "webpack-dev-server": "^2.4.5"
   }
 }

Diff for: examples/navigation-react-redux/store/index.js

@@ -2,8 +2,14 @@ import { createStore, applyMiddleware } from 'redux'
 // Use Ramda's compose instead of Redux's compose,
 // because we're already using it elsewhere.
 import compose from 'ramda/src/compose'
-import { createEpicMiddleware } from 'redux-most'
-// import { createEpicMiddleware } from '../../../src'
+import {
+  createEpicMiddleware,
+  createStateStreamEnhancer,
+} from 'redux-most'
+// import {
+//   createEpicMiddleware,
+//   createStateStreamEnhancer,
+// } from '../../../src'
 import { createLogger } from 'redux-logger'
 import { browserHistory } from 'react-router'
 import { routerMiddleware } from 'react-router-redux'
@@ -20,7 +26,7 @@ const logger = createLogger({
 
 const middleware = [
   logger,
-  epicMiddleware,
+  // epicMiddleware,
   routerMiddleware(browserHistory),
 ]
 
@@ -31,7 +37,10 @@ const composeEnhancers =
     })
     : compose
 
-const storeEnhancers = composeEnhancers(applyMiddleware(...middleware))
+const storeEnhancers = composeEnhancers(
+  createStateStreamEnhancer(epicMiddleware),
+  applyMiddleware(...middleware)
+)
 
 const store = createStore(rootReducer, storeEnhancers)
 

Diff for: examples/navigation-react-redux/webpack.config.dev.babel.js

@@ -38,9 +38,18 @@ const config = {
   module: {
     rules: [
       {
-        test: /\.(js|jsx)$/,
-        use: ['babel-loader'],
+        test: /\.js$/,
+        loader: 'babel-loader',
         exclude: /node_modules/,
+        query: {
+          'presets': [
+            ['env', {
+              'modules': false,
+            }],
+            'stage-3',
+            'react',
+          ],
+        },
       },
     ],
   },

Diff for: examples/navigation-react-redux/webpack.config.prod.babel.js

@@ -32,9 +32,18 @@ const config = {
   module: {
     rules: [
       {
-        test: /\.(js|jsx)$/,
-        use: ['babel-loader'],
+        test: /\.js$/,
+        loader: 'babel-loader',
         exclude: /node_modules/,
+        query: {
+          'presets': [
+            ['env', {
+              'modules': false,
+            }],
+            'stage-3',
+            'react',
+          ],
+        },
       },
     ],
   },