docs: ✏️ add api documentation for combine and compose fns

In order to make API more consistent, we changed function
composeCondition to composeIf

BREAKING CHANGE: 🧨 rename conditionDetector function to composeIf to make API more
consistent

Author: Piotr Oleś

README.md

@@ -41,8 +41,8 @@ To enable Redux Detector, use `createDetectorEnhancer`:
 ```js
 import { createStore } from "redux";
 import { createDetectorEnhancer } from "redux-detector";
-import rootReducer from "./reducers";
-import rootDetector from "./detectors";
+import { rootReducer } from "./store/reducer/rootReducer";
+import { rootDetector } from "./store/detector/rootDetector";
 
 const store = createStore(rootReducer, createDetectorEnhancer(rootDetector));
 ```
@@ -60,12 +60,12 @@ type Detector<TState, TResult> = (
 ) => TResult;
 ```
 
-The **`Actions Detector`** is a `Detector` which returns action, list of actions or nothing. 
+The **`Actions Detector`** is a `Detector` which returns action, list of actions or nothing.
 Returned actions are automatically dispatched by the enhancer.
 
 ```typescript
-import { Detector } from 'redux-detector';
-import { Action } from 'redux';
+import { Detector } from "redux-detector";
+import { Action } from "redux";
 
 type ActionsDetector<TState, TAction extends Action> = Detector<
   TState,
@@ -74,53 +74,54 @@ type ActionsDetector<TState, TAction extends Action> = Detector<
 ```
 
 Another type of the detector is the **`Condition Detector`** which returns boolean values.
+
 ```typescript
-import { Detector } from 'redux-detector';
+import { Detector } from "redux-detector";
 
 type ConditionDetector<TState> = Detector<TState, boolean>;
 ```
 
 These two types of detectors have different responsibility:
- * `Condition Detectors` describes a condition that we want to detect
- * `Actions Detectors` describes which action we want to dispatch
+
+- `Condition Detectors` describes a condition that we want to detect
+- `Actions Detectors` describes which action we want to dispatch
 
 Thanks to its functional nature and purity, detectors are easy to test. They don't break [Single Source of Truth principle](https://en.wikipedia.org/wiki/Single_source_of_truth)
 as the input is only previous and next state.
 
 ## Basics 👈
 
 Let's start simply - implement a condition detector that checks if number of login attempts exceeded 3.
+
 ```typescript
 export const exceededLoginAttemptsLimit = (prevState, nextState) =>
   prevState.attempts <= 3 && nextState.attempts > 3;
 ```
 
-We can make above example more generic - `prevState.attempts <= 3` is the same as `!(prevState.attempts > 3)`. 
-That means that we check if some condition is **not truthy** for the *previous state* but is **truthy** for the *next state*.
+We can make above example more generic - `prevState.attempts <= 3` is the same as `!(prevState.attempts > 3)`.
+That means that we check if some condition is **not truthy** for the _previous state_ but is **truthy** for the _next state_.
 This kind of transition can be handled by the `changedToTruthy` function.
 
 ```typescript
-import { changedToTruthy } from 'redux-detector';
+import { changedToTruthy } from "redux-detector";
 
 export const exceededLoginAttemptsLimit = changedToTruthy(
-  (state) => state.attempts > 3
+  state => state.attempts > 3
 );
 ```
 
-> Redux Detector library provides other useful functions to model condition detectors - please check the 
+> Redux Detector library provides other useful functions to model condition detectors - please check the
 > [API documentation](doc/api.md) to learn more.
 
-The next step is to use an action detector to dispatch an action when the limit became exceeded. 
-To do so, we will use `conditionDetector` function.
+The next step is to use an action detector to dispatch an action when the limit became exceeded.
+To do so, we will use `composeIf` function.
+
 ```typescript
-import {
-  conditionDetector,
-  changedToTruthy
-} from "redux-detector";
-import { blockUser } from '../action/userAction';
-
-const blockUserDetector = conditionDetector(
-  changedToTruthy((state) => state.attempts > 3),
+import { composeIf, changedToTruthy } from "redux-detector";
+import { blockUser } from "../action/userAction";
+
+const blockUserDetector = composeIf(
+  changedToTruthy(state => state.attempts > 3),
   () => blockUser()
 );
 ```
@@ -129,18 +130,21 @@ The `createDetectorEnhancer` function accepts only one detector, so we have to c
 detectors to the one `rootDetector`.
 
 ```typescript
-import { composeDetectors } from 'redux-detector';
-import { blockUserDetector } from './userDetector';
+import { composeDetectors } from "redux-detector";
+import { blockUserDetector } from "./userDetector";
 // other detectors...
-import { companyDetector } from './companyDetector';
+import { companyDetector } from "./companyDetector";
 
 export const rootDetector = composeDetectors(
   blockUserDetector,
   companyDetector
 );
 ```
 
+And that's all - `redux-detector` will dispatch `blockUser()` when login attempts exceeded 3 🎉
+
 ## [API reference 📖](doc/api.md)
+
 For more detailed documentation, please check API reference.
 
 ## Code splitting ✂️

doc/api.md

@@ -1,3 +1,158 @@
 ## Redux Detector API
 
-WIP
+The list of all available functions from the `redux-detector` package.
+
+## Redux related API
+
+### `createDetectorEnhancer(detector: ActionsDetector): StoreEnhancer`
+
+Creates new `StoreDetectableEnhancer` that can be passed as a second parameter of the
+`createStore` function from `redux`. This enhancer hooks into store's `dispatch` method
+and adds `replaceDetector` method.
+
+<details>
+<summary>Example:</summary>
+
+```js
+import { createStore } from "redux";
+import { createDetectorEnhancer } from "redux-detector";
+import { rootReducer } from "./store/rootReducer";
+import { rootDetector } from "./store/rootDetector";
+
+const store = createStore(rootReducer, createDetectorEnhancer(rootDetector));
+```
+
+</details>
+
+### `store.replaceDetector(detector: ActionsDetector): void`
+
+Features like hot-reloading or code splitting requires hooks to update rootDetector.
+You can do it via `replaceDetector` method available on an enhanced store.
+
+<details>
+<summary>Hot reloading example:</summary>
+
+```js
+if (module.hot) {
+  module.hot.accept("./store/rootReducer", async () => {
+    const {
+      rootReducer: nextRootReducer
+    } = await import("./store/rootReducer");
+    store.replaceReducer(nextRootReducer);
+  });
+  module.hot.accept("./store/rootDetector", async () => {
+    const {
+      rootDetector: nextRootDetector
+    } = await import("./store/rootDetector");
+    store.replaceDetector(nextRootDetector);
+  });
+}
+```
+
+</details>
+
+## Standard library API
+
+These functions are building blocks for creating more complex detectors.
+There is no hidden magic in these functions - they are simple and pure.
+
+### `composeDetectors(...detectors: ActionsDetector[]): ActionsDetector`
+
+Composes many actions detectors into one actions detector. If some of detectors
+returns an action or a list of actions, they are merged into one list of actions.
+
+<details>
+<summary>Example:</summary>
+
+```js
+import { composeDetectors } from "redux-detector";
+import { userDetector } from "./user/userDetector";
+import { companyDetector } from "./company/companyDetector";
+
+export const rootDetector = composeDetectors(userDetector, companyDetector);
+```
+
+</details>
+
+### `combineDetectors(map: ActionsDetectorsMap): ActionsDetector`
+
+Combines many actions detectors into one actions detector. The logic behind is the same
+as in the `combineReducers` function.
+
+<details>
+<summary>Example:</summary>
+
+```js
+import { combineDetectors } from "redux-detector";
+import { blockUser } from "./userActions";
+
+export const blockUserOnLoginAttemptsExceededDetector = combineDetectors({
+  login: combineDetectors({
+    attempts: (prevAttempts, nextAttempts) =>
+      prevAttempts < 3 && nextAttempts >= 3 ? blockUser() : undefined
+  })
+});
+```
+
+</details>
+
+### `composeAnd(...detectors: ConditionDetector[]): ConditionDetector`
+
+Composes many condition detectors into one condition detector using `and` operation on
+detectors output.
+
+<details>
+<summary>Example:</summary>
+
+```js
+import { composeAnd, isTruthy } from "redux-detector";
+import { exceededLoginLimit } from "./userDetector";
+import { isOnAdminZone } from "../security/securitySelector";
+
+export const exceededLimitOnAdminZone = composeAnd(
+  isTruthy(isOnAdminZone),
+  exceededLoginLimit
+);
+```
+
+</details>
+
+### `composeOr(...detectors: ConditionDetector[]): ConditionDetector`
+
+Composes many condition detectors into one condition detector using `or` operation on
+detectors output.
+
+<details>
+<summary>Example:</summary>
+
+```js
+import { composeOr } from "redux-detector";
+import { exceededLoginLimit, exceededResetPasswordLimit } from "./userDetector";
+
+export const exceededLoginOrResetPasswordLimit = composeOr(
+  exceededLoginLimit,
+  exceededResetPasswordLimit
+);
+```
+
+</details>
+
+### `composeIf(condition: ConditionDetector, actions: ActionsDetector): ActionsDetector`
+
+Creates actions detector that runs inner `actions` detector only if `condition` detector
+output is truthy.
+
+<details>
+<summary>Example:</summary>
+
+```js
+import { composeIf } from "redux-detector";
+import { exceededLoginLimit } from "./userDetector";
+import { blockUser } from "./userActions";
+
+const blockUserOnExceededLimitDetector = composeIf(exceededLoginLimit, () =>
+  blockUser()
+);
+```
+
+</details>

src/conditionDetector.ts renamed to src/composeIf.ts

@@ -1,6 +1,6 @@
 import { ActionsDetector, ConditionDetector } from "./Detector";
 
-export function conditionDetector<TState = any, TAction = any>(
+export function composeIf<TState = any, TAction = any>(
   condition: ConditionDetector<TState>,
   actions: ActionsDetector<TState, TAction>
 ): ActionsDetector<TState, TAction> {

src/index.ts

@@ -9,10 +9,10 @@ export { createDetectorEnhancer } from "./createDetectorEnhancer";
 // standard library
 export { composeDetectors } from "./composeDetectors";
 export { combineDetectors } from "./combineDetectors";
-export { conditionDetector } from "./conditionDetector";
 export { mapDetector } from "./mapDetector";
 export { mapNextState } from "./mapNextState";
 export { mapPrevState } from "./mapPrevState";
+export { composeIf } from "./composeIf";
 export { composeAnd } from "./composeAnd";
 export { composeOr } from "./composeOr";
 

test/conditionDetector.spec.ts

@@ -1,14 +1,14 @@
-import { conditionDetector } from "../src";
+import { composeIf } from "../src";
 
 describe("conditionDetector", () => {
   it("should export conditionDetector function", () => {
-    expect(conditionDetector).toBeInstanceOf(Function);
+    expect(composeIf).toBeInstanceOf(Function);
   });
 
   it("should return conditional detector", () => {
     const action = { type: "ACTION" };
     const detector = jest.fn(() => action);
-    const conditionalDetector = conditionDetector(
+    const conditionalDetector = composeIf(
       (prevState?: number, nextState?: number) =>
         !!(prevState && nextState && prevState < nextState),
       detector

test/integration/compose.spec.ts

@@ -1,8 +1,8 @@
 import {
   changedAndTruthy,
   composeAnd,
+  composeIf,
   composeOr,
-  conditionDetector,
   isTruthy,
   mapNextState
 } from "../../src";
@@ -18,7 +18,7 @@ describe("detectors compose", () => {
   const isAPositive = (state: State | undefined) => state && getA(state) > 0;
   const action = (payload: any) => ({ type: "DETECTED", payload });
 
-  const detector = conditionDetector<State>(
+  const detector = composeIf<State>(
     composeAnd(
       isTruthy(isANotNegative),
       composeOr(changedAndTruthy(isAZero), isTruthy(isAPositive))