feat: 🎸 Create more generic Detector<TState, TResult> type

Renamed Detector<S> to ActionsDetector<TState, TAction> in order to
create more generic Detector<TState, TResult> type. Added
ConditionDetector<TState> type. Added typings for TAction type (by
default AnyAction).

BREAKING CHANGE: 🧨 Renamed type Detector<S> to ActionsDetector<TState, TAction> and added
Detector<TState, TResult> type (more generic).

Author: Piotr Oleś

src/Detector.ts

@@ -1,4 +1,22 @@
+import { Action, AnyAction } from "redux";
+
 /**
- * Function that compares previous and next state and can return action, array of actions or undefined.
+ * Function that reduces previous and next state to single value.
  */
-export type Detector<S> = (prevState?: S, nextState?: S) => any | any[] | void;
+export type Detector<TState = any, TResult = any> = (
+  prevState?: TState,
+  nextState?: TState
+) => TResult;
+
+/**
+ * Function that compares previous and next state and can return action, array of actions or nothing.
+ */
+export type ActionsDetector<
+  TState = any,
+  TAction extends Action = AnyAction
+> = Detector<TState, TAction | TAction[] | void>;
+
+/**
+ * Function that compares previous and next state and returns boolean value
+ */
+export type ConditionDetector<TState = any> = Detector<TState, boolean>;

src/DetectorsMap.ts

@@ -1,7 +1,7 @@
 import { Reducer, Store, StoreEnhancer } from "redux";
 import { DetectableStore } from "./DetectableStore";
 import { DetectableStoreExt } from "./DetectableStoreExt";
-import { Detector } from "./Detector";
+import { ActionsDetector } from "./Detector";
 
 export const ActionTypes: { INIT: string } = {
   INIT: "@@detector/INIT"
@@ -15,11 +15,11 @@ export type StoreDetectableEnhancer<S> = StoreEnhancer<
 /**
  * Creates detector enhancer that modifies redux store to use it with provided detector.
  *
- * @param detector Root detector
+ * @param detector Root actions detector
  * @returns Store enhancer
  */
 export function createDetectorEnhancer<S = any>(
-  detector: Detector<S>
+  detector: ActionsDetector<S>
 ): StoreDetectableEnhancer<S> {
   if (typeof detector !== "function") {
     throw new Error("Expected the detector to be a function.");
@@ -43,7 +43,7 @@ export function createDetectorEnhancer<S = any>(
       const detectableStore: DetectableStore<any, any> = {
         ...store,
         replaceDetector: function replaceDetector(
-          nextDetector: Detector<any>
+          nextDetector: ActionsDetector<any>
         ): void {
           if (typeof nextDetector !== "function") {
             throw new Error("Expected the nextDetector to be a function.");

src/createDetectorEnhancer.ts

@@ -6,7 +6,7 @@ export { DetectableStoreExt } from "./DetectableStoreExt";
 // enhance redux store
 export { createDetectorEnhancer } from "./createDetectorEnhancer";
 
-// reduce detectors
+// standard library
 export { reduceDetectors } from "./lib/reduceDetectors";
 export { combineDetectors } from "./lib/combineDetectors";
 export { mountDetector } from "./lib/mountDetector";

src/index.ts

@@ -1,5 +1,10 @@
-import { Detector } from "../Detector";
-import { DetectorsMap } from "../DetectorsMap";
+import { Action, AnyAction } from "redux";
+import { ActionsDetector } from "../Detector";
+
+type ActionsDetectorsMap<
+  TState extends object,
+  TAction extends Action = AnyAction
+> = { [K in keyof TState]?: ActionsDetector<TState[K], TAction> };
 
 /**
  * Combine detectors to bind them to the local state.
@@ -8,17 +13,18 @@ import { DetectorsMap } from "../DetectorsMap";
  * @param map Map of detectors bounded to state.
  * @returns Combined detector
  */
-export function combineDetectors<S extends object>(
-  map: DetectorsMap<S>
-): Detector<S> {
+export function combineDetectors<
+  TState extends object,
+  TAction extends Action = AnyAction
+>(map: ActionsDetectorsMap<TState, TAction>): ActionsDetector<TState, TAction> {
   return function combinedDetector(
-    prevState: S | undefined,
-    nextState: S | undefined
+    prevState?: TState,
+    nextState?: TState
   ): any[] {
     return Object.keys(map).reduce((reducedActions: any[], key: string) => {
-      let actions: any | any[] | void = map[key as keyof S]!(
-        prevState ? prevState[key as keyof S] : undefined,
-        nextState ? nextState[key as keyof S] : undefined
+      let actions: any | any[] | void = map[key as keyof TState]!(
+        prevState ? prevState[key as keyof TState] : undefined,
+        nextState ? nextState[key as keyof TState] : undefined
       );
 
       if (actions) {

src/lib/combineDetectors.ts

@@ -1,13 +1,20 @@
 import { Detector } from "../Detector";
 
-export function mountDetector<TOuterState, TState>(
-  selector: (state: TOuterState | undefined) => TState,
-  detector: Detector<TState>
-): Detector<TOuterState> {
+/**
+ * Mounts detector to selected state using selectors. Works perfectly with reselect library.
+ */
+export function mountDetector<
+  TOuterState = any,
+  TInnerState = any,
+  TResult = any
+>(
+  selector: (state: TOuterState | undefined) => TInnerState,
+  detector: Detector<TInnerState, TResult>
+): Detector<TOuterState, TResult> {
   return function mountedDetector(
     prevState: TOuterState | undefined,
     nextState: TOuterState | undefined
-  ): any | any[] | void {
+  ): TResult {
     return detector(selector(prevState), selector(nextState));
   };
 }

src/lib/mountDetector.ts

@@ -1,6 +1,12 @@
-import { Detector } from "../Detector";
+import { Action, AnyAction } from "redux";
+import { ActionsDetector } from "../Detector";
 
-export function reduceDetectors<S>(...detectors: Detector<S>[]): Detector<S> {
+/**
+ * Compose many action detectors into one detector that aggregates actions returned by given detectors
+ */
+export function reduceDetectors<TState, TAction extends Action = AnyAction>(
+  ...detectors: ActionsDetector<TState, TAction>[]
+): ActionsDetector<TState, TAction> {
   // check detectors types in runtime
   const invalidDetectorsIndexes: number[] = detectors
     .map((detector, index) => (detector instanceof Function ? -1 : index))
@@ -19,11 +25,14 @@ export function reduceDetectors<S>(...detectors: Detector<S>[]): Detector<S> {
   }
 
   return function reducedDetector(
-    prevState: S | undefined,
-    nextState: S | undefined
+    prevState: TState | undefined,
+    nextState: TState | undefined
   ): any[] {
     return detectors
       .map(detector => detector(prevState, nextState) || [])
-      .reduce((actions, nextActions) => actions.concat(nextActions), []);
+      .reduce(
+        (actions: TAction[], nextActions) => actions.concat(nextActions),
+        []
+      );
   };
 }

src/lib/reduceDetectors.ts

@@ -1,18 +1,17 @@
+import { reduceDetectors } from "../src";
 
-import { reduceDetectors } from '../src';
-
-describe('reduceDetectors', () => {
-  it('should export reduceDetectors function', () => {
+describe("reduceDetectors", () => {
+  it("should export composeDetectors function", () => {
     expect(reduceDetectors).toBeInstanceOf(Function);
   });
 
-  it('should return valid detector for reduction of two detectors', () => {
+  it("should return valid detector for composition of two detectors", () => {
     function detectorA() {
-      return [{type: 'ACTION_A'}, {type: 'ACTION_B'}];
+      return [{ type: "ACTION_A" }, { type: "ACTION_B" }];
     }
 
     function detectorB() {
-      return [{type: 'ACTION_C'}];
+      return [{ type: "ACTION_C" }];
     }
 
     const detectorAB = reduceDetectors(detectorA, detectorB);
@@ -21,75 +20,90 @@ describe('reduceDetectors', () => {
     expect(detectorAB({}, {})).toBeInstanceOf(Array);
 
     // we check it twice to be sure that detectorAB doesn't has any internal state.
-    expect(detectorAB({}, {})).toEqual([{type: 'ACTION_A'}, {type: 'ACTION_B'}, {type: 'ACTION_C'}]);
-    expect(detectorAB({}, {})).toEqual([{type: 'ACTION_A'}, {type: 'ACTION_B'}, {type: 'ACTION_C'}]);
+    expect(detectorAB({}, {})).toEqual([
+      { type: "ACTION_A" },
+      { type: "ACTION_B" },
+      { type: "ACTION_C" }
+    ]);
+    expect(detectorAB({}, {})).toEqual([
+      { type: "ACTION_A" },
+      { type: "ACTION_B" },
+      { type: "ACTION_C" }
+    ]);
   });
 
-  it('should pass states in valid order for reduction of two detectors', () => {
+  it("should pass states in valid order for composition of two detectors", () => {
     function detectorA(prevState?: number, nextState?: number) {
       if (prevState && nextState && prevState > nextState) {
-        return [{type: 'PREV_STATE_GREATER'}];
+        return [{ type: "PREV_STATE_GREATER" }];
       }
 
       return [];
     }
 
     function detectorB(prevState?: number, nextState?: number) {
       if (prevState && nextState && nextState > prevState) {
-        return [{type: 'NEXT_STATE_GREATER'}];
+        return [{ type: "NEXT_STATE_GREATER" }];
       }
 
       return [];
     }
 
     const detectorAB = reduceDetectors(detectorA, detectorB);
 
-    expect(detectorAB(-10, 50)).toEqual([{type: 'NEXT_STATE_GREATER'}]);
-    expect(detectorAB(30, 20)).toEqual([{type: 'PREV_STATE_GREATER'}]);
+    expect(detectorAB(-10, 50)).toEqual([{ type: "NEXT_STATE_GREATER" }]);
+    expect(detectorAB(30, 20)).toEqual([{ type: "PREV_STATE_GREATER" }]);
   });
 
-  it('should allow to reduce detectors with undefined result on no-action detect', () => {
+  it("should allow to compose detectors with undefined result on no-action detect", () => {
     function detectorA(prevState?: number, nextState?: number) {
       if (prevState && nextState && prevState > nextState) {
-        return [{type: 'PREV_STATE_GREATER'}];
+        return [{ type: "PREV_STATE_GREATER" }];
       }
     }
 
     function detectorB(prevState?: number, nextState?: number) {
       if (prevState && nextState && nextState > prevState) {
-        return [{type: 'NEXT_STATE_GREATER'}];
+        return [{ type: "NEXT_STATE_GREATER" }];
       }
     }
 
     const detectorAB = reduceDetectors(detectorA, detectorB);
 
-    expect(detectorAB(-10, 50)).toEqual([{type: 'NEXT_STATE_GREATER'}]);
-    expect(detectorAB(30, 20)).toEqual([{type: 'PREV_STATE_GREATER'}]);
+    expect(detectorAB(-10, 50)).toEqual([{ type: "NEXT_STATE_GREATER" }]);
+    expect(detectorAB(30, 20)).toEqual([{ type: "PREV_STATE_GREATER" }]);
   });
 
-  it('should allow to reduce detectors with array and single result', () => {
+  it("should allow to compose detectors with array and single result", () => {
     function detectorA() {
-      return [{type: 'ARRAY_DETECTOR'}];
+      return [{ type: "ARRAY_DETECTOR" }];
     }
 
     function detectorB() {
-      return {type: 'SINGLE_DETECTOR'};
+      return { type: "SINGLE_DETECTOR" };
     }
 
     const detectorAB = reduceDetectors(detectorA, detectorB);
 
-    expect(detectorAB(undefined, undefined)).toEqual([{type: 'ARRAY_DETECTOR'}, {type: 'SINGLE_DETECTOR'}]);
+    expect(detectorAB(undefined, undefined)).toEqual([
+      { type: "ARRAY_DETECTOR" },
+      { type: "SINGLE_DETECTOR" }
+    ]);
   });
 
-  it('should return valid reduced detector for empty arguments', () => {
+  it("should return valid composed detector for empty arguments", () => {
     const emptyDetector = reduceDetectors();
 
     expect(emptyDetector).toBeInstanceOf(Function);
     expect(emptyDetector(10, 20)).toEqual([]);
   });
 
-  it('should throw an exception for invalid arguments', () => {
-    expect(() => { (reduceDetectors as any)({ 'foo': 'bar' }); }).toThrow();
-    expect(() => { (reduceDetectors as any)(() => undefined, undefined); }).toThrow();
+  it("should throw an exception for invalid arguments", () => {
+    expect(() => {
+      (reduceDetectors as any)({ foo: "bar" });
+    }).toThrow();
+    expect(() => {
+      (reduceDetectors as any)(() => undefined, undefined);
+    }).toThrow();
   });
 });