Allow control over internal state using a state reducer and dispatcher (#46)

* Add 'reducer' and 'dispatcher' options to allow external control over internal state.

* Re-enable all tests.

* Invoke the promiseFn from the dispatcher so we can control its invocation.

Author: ghengeveld

README.md

@@ -298,6 +298,8 @@ These can be passed in an object to `useAsync()`, or as props to `<Async>` and c
 - `initialValue` Provide initial data or error for server-side rendering.
 - `onResolve` Callback invoked when Promise resolves.
 - `onReject` Callback invoked when Promise rejects.
+- `reducer` State reducer to control internal state updates.
+- `dispatcher` Action dispatcher to control internal action dispatching.
 
 `useFetch` additionally takes these options:
 
@@ -371,6 +373,21 @@ Callback function invoked when a promise resolves, receives data as argument.
 
 Callback function invoked when a promise rejects, receives rejection reason (error) as argument.
 
+#### `reducer`
+
+> `function(state: any, action: Object, internalReducer: function(state: any, action: Object))`
+
+State reducer to take full control over state updates by wrapping the internal reducer. It receives the current state,
+the dispatched action and the internal reducer. You probably want to invoke the internal reducer at some point.
+
+#### `dispatcher`
+
+> `function(action: Object, internalDispatch: function(action: Object), props: Object)`
+
+Action dispatcher to take full control over action dispatching by wrapping the internal dispatcher. It receives the
+original action, the internal dispatcher and all component props (or options). You probably want to invoke the internal
+dispatcher at some point.
+
 #### `defer`
 
 > `boolean`
@@ -602,7 +619,9 @@ Alias: `<Async.Resolved>`
 ```
 
 ```jsx
-<Async.Fulfilled>{(data, { finishedAt }) => `Last updated ${finishedAt.toISOString()}`}</Async.Fulfilled>
+<Async.Fulfilled>
+  {(data, { finishedAt }) => `Last updated ${finishedAt.toISOString()}`}
+</Async.Fulfilled>
 ```
 
 ### `<Async.Rejected>`

src/Async.js

@@ -1,5 +1,5 @@
 import React from "react"
-import { actionTypes, init, reducer } from "./reducer"
+import { actionTypes, init, dispatchMiddleware, reducer as asyncReducer } from "./reducer"
 
 let PropTypes
 try {
@@ -49,7 +49,16 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
         setData: this.setData,
         setError: this.setError,
       }
-      this.dispatch = (action, callback) => this.setState(state => reducer(state, action), callback)
+
+      const _reducer = props.reducer || defaultProps.reducer
+      const _dispatcher = props.dispatcher || defaultProps.dispatcher
+      const reducer = _reducer
+        ? (state, action) => _reducer(state, action, asyncReducer)
+        : asyncReducer
+      const dispatch = dispatchMiddleware((action, callback) => {
+        this.setState(state => reducer(state, action), callback)
+      })
+      this.dispatch = _dispatcher ? action => _dispatcher(action, dispatch, props) : dispatch
     }
 
     componentDidMount() {
@@ -79,26 +88,38 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
       this.mounted = false
     }
 
-    start() {
+    getMeta(meta) {
+      return {
+        counter: this.counter,
+        ...meta,
+      }
+    }
+
+    start(promiseFn) {
       if ("AbortController" in window) {
         this.abortController.abort()
         this.abortController = new window.AbortController()
       }
       this.counter++
-      this.mounted && this.dispatch({ type: actionTypes.start, meta: { counter: this.counter } })
+      return new Promise((resolve, reject) => {
+        if (!this.mounted) return
+        const executor = () => promiseFn().then(resolve, reject)
+        this.dispatch({ type: actionTypes.start, payload: executor, meta: this.getMeta() })
+      })
     }
 
     load() {
       const promise = this.props.promise
       if (promise) {
-        this.start()
-        return promise.then(this.onResolve(this.counter), this.onReject(this.counter))
+        return this.start(() => promise).then(
+          this.onResolve(this.counter),
+          this.onReject(this.counter)
+        )
       }
-
       const promiseFn = this.props.promiseFn || defaultProps.promiseFn
       if (promiseFn) {
-        this.start()
-        return promiseFn(this.props, this.abortController).then(
+        const props = { ...defaultProps, ...this.props }
+        return this.start(() => promiseFn(props, this.abortController)).then(
           this.onResolve(this.counter),
           this.onReject(this.counter)
         )
@@ -109,8 +130,8 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
       const deferFn = this.props.deferFn || defaultProps.deferFn
       if (deferFn) {
         this.args = args
-        this.start()
-        return deferFn(args, { ...defaultProps, ...this.props }, this.abortController).then(
+        const props = { ...defaultProps, ...this.props }
+        return this.start(() => deferFn(args, props, this.abortController)).then(
           this.onResolve(this.counter),
           this.onReject(this.counter)
         )
@@ -120,7 +141,7 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
     cancel() {
       this.counter++
       this.abortController.abort()
-      this.mounted && this.dispatch({ type: actionTypes.cancel, meta: { counter: this.counter } })
+      this.mounted && this.dispatch({ type: actionTypes.cancel, meta: this.getMeta() })
     }
 
     onResolve(counter) {
@@ -144,13 +165,17 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
     }
 
     setData(data, callback) {
-      this.mounted && this.dispatch({ type: actionTypes.fulfill, payload: data }, callback)
+      this.mounted &&
+        this.dispatch({ type: actionTypes.fulfill, payload: data, meta: this.getMeta() }, callback)
       return data
     }
 
     setError(error, callback) {
       this.mounted &&
-        this.dispatch({ type: actionTypes.reject, payload: error, error: true }, callback)
+        this.dispatch(
+          { type: actionTypes.reject, payload: error, error: true, meta: this.getMeta() },
+          callback
+        )
       return error
     }
 
@@ -177,6 +202,8 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
       initialValue: PropTypes.any,
       onResolve: PropTypes.func,
       onReject: PropTypes.func,
+      reducer: PropTypes.func,
+      dispatcher: PropTypes.func,
     }
   }
 

src/Async.spec.js

@@ -12,6 +12,8 @@ import {
   withPromise,
   withPromiseFn,
   withDeferFn,
+  withReducer,
+  withDispatcher,
 } from "./specs"
 
 const abortCtrl = { abort: jest.fn() }
@@ -25,6 +27,8 @@ describe("Async", () => {
   describe("with `promise`", withPromise(Async, abortCtrl))
   describe("with `promiseFn`", withPromiseFn(Async, abortCtrl))
   describe("with `deferFn`", withDeferFn(Async, abortCtrl))
+  describe("with `reducer`", withReducer(Async, abortCtrl))
+  describe("with `dispatcher`", withDispatcher(Async, abortCtrl))
 
   test("an unrelated change in props does not update the Context", async () => {
     let one

src/reducer.js

@@ -53,5 +53,14 @@ export const reducer = (state, { type, payload, meta }) => {
         finishedAt: new Date(),
         ...getStatusProps(statusTypes.rejected),
       }
+    default:
+      return state
+  }
+}
+
+export const dispatchMiddleware = dispatch => (action, ...args) => {
+  dispatch(action, ...args)
+  if (action.type === actionTypes.start && typeof action.payload === "function") {
+    action.payload()
   }
 }

src/specs.js

@@ -9,6 +9,7 @@ export const resolveTo = resolveIn(0)
 export const rejectIn = ms => err =>
   new Promise((resolve, reject) => setTimeout(reject, ms, new Error(err)))
 export const rejectTo = rejectIn(0)
+export const sleep = ms => resolveIn(ms)()
 
 export const common = Async => () => {
   test("passes `data`, `error`, metadata and methods as render props", async () => {
@@ -99,22 +100,22 @@ export const withPromise = Async => () => {
   test("invokes `onResolve` callback when the promise resolves", async () => {
     const onResolve = jest.fn()
     render(<Async promise={resolveTo("ok")} onResolve={onResolve} />)
-    await resolveTo()
+    await sleep(10)
     expect(onResolve).toHaveBeenCalledWith("ok")
   })
 
   test("invokes `onReject` callback when the promise rejects", async () => {
     const onReject = jest.fn()
     render(<Async promise={rejectTo("err")} onReject={onReject} />)
-    await resolveTo()
+    await sleep(10)
     expect(onReject).toHaveBeenCalledWith(new Error("err"))
   })
 
   test("cancels a pending promise when unmounted", async () => {
     const onResolve = jest.fn()
     const { unmount } = render(<Async promise={resolveTo("ok")} onResolve={onResolve} />)
     unmount()
-    await resolveTo()
+    await sleep(10)
     expect(onResolve).not.toHaveBeenCalled()
   })
 
@@ -124,7 +125,7 @@ export const withPromise = Async => () => {
     const onResolve = jest.fn()
     const { rerender } = render(<Async promise={promise1} onResolve={onResolve} />)
     rerender(<Async promise={promise2} onResolve={onResolve} />)
-    await resolveTo()
+    await sleep(10)
     expect(onResolve).not.toHaveBeenCalledWith("one")
     expect(onResolve).toHaveBeenCalledWith("two")
   })
@@ -133,7 +134,7 @@ export const withPromise = Async => () => {
     const onResolve = jest.fn()
     const { rerender } = render(<Async promise={resolveTo()} onResolve={onResolve} />)
     rerender(<Async onResolve={onResolve} />)
-    await resolveTo()
+    await sleep(10)
     expect(onResolve).not.toHaveBeenCalled()
   })
 
@@ -191,14 +192,14 @@ export const withPromiseFn = (Async, abortCtrl) => () => {
   test("invokes `onResolve` callback when the promise resolves", async () => {
     const onResolve = jest.fn()
     render(<Async promiseFn={() => resolveTo("ok")} onResolve={onResolve} />)
-    await resolveTo()
+    await sleep(10)
     expect(onResolve).toHaveBeenCalledWith("ok")
   })
 
   test("invokes `onReject` callback when the promise rejects", async () => {
     const onReject = jest.fn()
     render(<Async promiseFn={() => rejectTo("err")} onReject={onReject} />)
-    await resolveTo()
+    await sleep(10)
     expect(onReject).toHaveBeenCalledWith(new Error("err"))
   })
 
@@ -280,7 +281,7 @@ export const withPromiseFn = (Async, abortCtrl) => () => {
     const onResolve = jest.fn()
     const { unmount } = render(<Async promiseFn={() => resolveTo("ok")} onResolve={onResolve} />)
     unmount()
-    await resolveTo()
+    await sleep(10)
     expect(onResolve).not.toHaveBeenCalled()
     expect(abortCtrl.abort).toHaveBeenCalledTimes(1)
   })
@@ -291,7 +292,7 @@ export const withPromiseFn = (Async, abortCtrl) => () => {
     const onResolve = jest.fn()
     const { rerender } = render(<Async promiseFn={promiseFn1} onResolve={onResolve} />)
     rerender(<Async promiseFn={promiseFn2} onResolve={onResolve} />)
-    await resolveTo()
+    await sleep(10)
     expect(onResolve).not.toHaveBeenCalledWith("one")
     expect(onResolve).toHaveBeenCalledWith("two")
     expect(abortCtrl.abort).toHaveBeenCalledTimes(1)
@@ -301,15 +302,15 @@ export const withPromiseFn = (Async, abortCtrl) => () => {
     const onResolve = jest.fn()
     const { rerender } = render(<Async promiseFn={() => resolveTo()} onResolve={onResolve} />)
     rerender(<Async onResolve={onResolve} />)
-    await resolveTo()
+    await sleep(10)
     expect(onResolve).not.toHaveBeenCalled()
     expect(abortCtrl.abort).toHaveBeenCalledTimes(1)
   })
 
   test("does not run `promiseFn` on mount when `initialValue` is provided", async () => {
     const promiseFn = jest.fn().mockReturnValue(resolveTo())
     render(<Async promiseFn={promiseFn} initialValue={{}} />)
-    await resolveTo()
+    await sleep(10)
     expect(promiseFn).not.toHaveBeenCalled()
   })
 
@@ -415,3 +416,81 @@ export const withDeferFn = (Async, abortCtrl) => () => {
     await waitForElement(() => getByText("done"))
   })
 }
+
+export const withReducer = Async => () => {
+  test("receives state, action and the original reducer", async () => {
+    const promise = resolveTo("done")
+    const reducer = jest.fn((state, action, asyncReducer) => asyncReducer(state, action))
+    const { getByText } = render(
+      <Async promise={promise} reducer={reducer}>
+        {({ data }) => data || null}
+      </Async>
+    )
+    await waitForElement(() => getByText("done"))
+    expect(reducer).toHaveBeenCalledWith(
+      expect.objectContaining({ status: expect.any(String) }),
+      expect.objectContaining({ type: expect.any(String) }),
+      expect.any(Function)
+    )
+  })
+
+  test("allows overriding state updates", async () => {
+    const promise = resolveTo("done")
+    const reducer = (state, action, asyncReducer) => {
+      if (action.type === "fulfill") action.payload = "cool"
+      return asyncReducer(state, action)
+    }
+    const { getByText } = render(
+      <Async promise={promise} reducer={reducer}>
+        {({ data }) => data || null}
+      </Async>
+    )
+    await waitForElement(() => getByText("cool"))
+  })
+}
+
+export const withDispatcher = Async => () => {
+  test("receives action, the original dispatch method and options", async () => {
+    const promise = resolveTo("done")
+    const dispatcher = jest.fn((action, dispatch) => dispatch(action))
+    const props = { promise, dispatcher }
+    const { getByText } = render(<Async {...props}>{({ data }) => data || null}</Async>)
+    await waitForElement(() => getByText("done"))
+    expect(dispatcher).toHaveBeenCalledWith(
+      expect.objectContaining({ type: expect.any(String) }),
+      expect.any(Function),
+      expect.objectContaining(props)
+    )
+  })
+
+  test("allows overriding actions before dispatch", async () => {
+    const promise = resolveTo("done")
+    const dispatcher = (action, dispatch) => {
+      if (action.type === "fulfill") action.payload = "cool"
+      dispatch(action)
+    }
+    const { getByText } = render(
+      <Async promise={promise} dispatcher={dispatcher}>
+        {({ data }) => data || null}
+      </Async>
+    )
+    await waitForElement(() => getByText("cool"))
+  })
+
+  test("allows dispatching additional actions", async () => {
+    const promise = resolveTo("done")
+    const customAction = { type: "custom" }
+    const dispatcher = (action, dispatch) => {
+      dispatch(action)
+      dispatch(customAction)
+    }
+    const reducer = jest.fn((state, action, asyncReducer) => asyncReducer(state, action))
+    const { getByText } = render(
+      <Async promise={promise} dispatcher={dispatcher} reducer={reducer}>
+        {({ data }) => data || null}
+      </Async>
+    )
+    await waitForElement(() => getByText("done"))
+    expect(reducer).toHaveBeenCalledWith(expect.anything(), customAction, expect.anything())
+  })
+}