Improve docs and tests

Author: tommasoberlose

src/extraReducersBuilder.ts

@@ -1,4 +1,9 @@
-import { Action, ActionReducerMapBuilder, CaseReducer, Draft } from "@reduxjs/toolkit";
+import {
+  Action,
+  ActionReducerMapBuilder,
+  CaseReducer,
+  Draft,
+} from '@reduxjs/toolkit';
 
 /**
  * A higher-order reducer that wraps a case reducer and invokes a callback
@@ -9,23 +14,33 @@ import { Action, ActionReducerMapBuilder, CaseReducer, Draft } from "@reduxjs/to
  * @returns The wrapped case reducer.
  * @internal
  */
-const persistReducer = <SliceState>(r: CaseReducer<SliceState, Action>, onStateUpdate: (s: Draft<SliceState>, a: Action) => void) => (s: Draft<SliceState>, a: Action): void | SliceState | Draft<SliceState> => {
-  const ns = r(s, a);
-  onStateUpdate(s, a);
-  if (ns) return ns;
-};
+const persistReducer =
+  <SliceState>(
+    r: CaseReducer<SliceState, Action>,
+    onStateUpdate: (s: Draft<SliceState>, a: Action) => void,
+  ) =>
+  (
+    s: Draft<SliceState>,
+    a: Action,
+  ): void | SliceState | Draft<SliceState> => {
+    const ns = r(s, a);
+    onStateUpdate(s, a);
+    if (ns) return ns;
+  };
 
 /**
- * A wrapper for the `ActionReducerMapBuilder` that automatically hooks into
- * state changes to track updates for persistence. Every reducer added via this
- * builder will be wrapped to call the `onStateUpdate` callback.
+ * A proxy for the `ActionReducerMapBuilder` that intercepts calls to `addCase`,
+ * `addMatcher`, and `addDefaultCase`. It wraps the provided reducers with
+ * persistence logic, ensuring that the `onStateUpdate` callback is triggered
+ * after any state change.
  *
  * @param builder The original `ActionReducerMapBuilder` from Redux Toolkit.
- * @param onStateUpdate The callback to invoke after any case reducer has been executed. It receives the state draft and the action.
- *
+ * @param onStateUpdate The callback to invoke after any case reducer has been
+ * executed. It receives the state draft and the action.
  * @internal
  */
-export class Builder<SliceState> implements ActionReducerMapBuilder<SliceState>
+export class Builder<SliceState>
+  implements ActionReducerMapBuilder<SliceState>
 {
   builder: ActionReducerMapBuilder<SliceState>;
   onStateUpdate: (s: Draft<SliceState>, a: Action) => void;
@@ -44,95 +59,33 @@ export class Builder<SliceState> implements ActionReducerMapBuilder<SliceState>
   }
 
   /**
-     * Adds a "default case" reducer that is executed if no case reducer and no matcher
-     * reducer was executed for this action.
-     * @param reducer - The fallback "default case" reducer function.
-     *
-     * @example
-  ```ts
-  import { createReducer } from '@reduxjs/toolkit'
-  const initialState = { otherActions: 0 }
-  const reducer = createReducer(initialState, builder => {
-    builder
-      // .addCase(...)
-      // .addMatcher(...)
-      .addDefaultCase((state, action) => {
-        state.otherActions++
-      })
-  })
-  ```
-     */
+   * Wraps and adds a "default case" reducer. This behaves like the
+   * original `builder.addDefaultCase` but also triggers the persistence
+   * callback upon execution.
+   * @param reducer - The fallback "default case" reducer function.
+   */
   addDefaultCase(r: CaseReducer<SliceState, Action>) {
     this.builder.addDefaultCase(persistReducer(r, this.onStateUpdate));
     return this;
   }
 
   /**
-   * Allows you to match your incoming actions against your own filter function instead of only the `action.type` property.
-   * @remarks
-   * If multiple matcher reducers match, all of them will be executed in the order
-   * they were defined in - even if a case reducer already matched.
-   * All calls to `builder.addMatcher` must come after any calls to `builder.addCase` and before any calls to `builder.addDefaultCase`.
-   * @param matcher - A matcher function. In TypeScript, this should be a [type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates)
-   * function
+   * Wraps and adds a matcher reducer. This behaves like the original
+   * `builder.addMatcher` but also triggers the persistence callback
+   * upon execution.
+   * @param matcher - A matcher function to filter actions.
    * @param reducer - The actual case reducer function.
-   *
-   * @example
-  ```ts
-  import {
-    createAction,
-    createReducer,
-    AsyncThunk,
-    UnknownAction,
-  } from "@reduxjs/toolkit";
-
-  type GenericAsyncThunk = AsyncThunk<unknown, unknown, any>;
-
-  type PendingAction = ReturnType<GenericAsyncThunk["pending"]>;
-  type RejectedAction = ReturnType<GenericAsyncThunk["rejected"]>;
-  type FulfilledAction = ReturnType<GenericAsyncThunk["fulfilled"]>;
-
-  const initialState: Record<string, string> = {};
-  const resetAction = createAction("reset-tracked-loading-state");
-
-  function isPendingAction(action: UnknownAction): action is PendingAction {
-    return typeof action.type === "string" && action.type.endsWith("/pending");
-  }
-
-  const reducer = createReducer(initialState, (builder) => {
-    builder
-      .addCase(resetAction, () => initialState)
-      // matcher can be defined outside as a type predicate function
-      .addMatcher(isPendingAction, (state, action) => {
-        state[action.meta.requestId] = "pending";
-      })
-      .addMatcher(
-        // matcher can be defined inline as a type predicate function
-        (action): action is RejectedAction => action.type.endsWith("/rejected"),
-        (state, action) => {
-          state[action.meta.requestId] = "rejected";
-        }
-      )
-      // matcher can just return boolean and the matcher can receive a generic argument
-      .addMatcher<FulfilledAction>(
-        (action) => action.type.endsWith("/fulfilled"),
-        (state, action) => {
-          state[action.meta.requestId] = "fulfilled";
-        }
-      );
-  });
-  ```
-     */
+   */
   addMatcher(p: any, r: CaseReducer<SliceState, any>) {
     this.builder.addMatcher(p, persistReducer(r, this.onStateUpdate));
     return this;
   }
 
   /**
-   * Adds a case reducer to handle a single exact action type.
-   * @remarks
-   * All calls to `builder.addCase` must come before any calls to `builder.addMatcher` or `builder.addDefaultCase`.
-   * @param actionCreator - Either a plain action type string, or an action creator generated by [`createAction`](./createAction) that can be used to determine the action type.
+   * Wraps and adds a case reducer to handle a single action type. This
+   * behaves like the original `builder.addCase` but also triggers the
+   * persistence callback upon execution.
+   * @param actionCreator - The action creator or type string to match against.
    * @param reducer - The actual case reducer function.
    */
   addCase(ac: string, r: CaseReducer<SliceState, any>) {

src/index.ts

@@ -1,15 +1,33 @@
 /**
  * @module rtk-persist
- * @description This is the main entry point for the rtk-persist library.
- * It exports the core functions needed to add persistence capabilities
- * to a Redux Toolkit application.
+ * @description
+ * The main entry point for the `rtk-persist` library. This module exports the
+ * necessary functions to seamlessly integrate persistence into your Redux Toolkit
+ * applications. Whether you're setting up a new store, creating individual
+ * persisted slices, or wrapping existing reducers, these utilities provide
+ * a simple and efficient way to save and rehydrate your Redux state.
  */
 import { createPersistedReducer } from './reducer';
-import { createPersistedSlice } from "./slice";
-import { configurePersistedStore } from "./store";
+import { createPersistedSlice } from './slice';
+import { configurePersistedStore } from './store';
 
 export {
+  /**
+   * A wrapper around Redux Toolkit's `configureStore` that automatically
+   * sets up the persistence middleware and initial state rehydration.
+   * Use this for a quick and easy setup of a fully persisted store.
+   */
   configurePersistedStore,
+  /**
+   * A utility to wrap an existing reducer with persistence logic. This is
+   * useful when you need to add persistence to a reducer that was not
+   * created with `createPersistedSlice`.
+   */
   createPersistedReducer,
+  /**
+   * A wrapper around Redux Toolkit's `createSlice` that adds persistence
+   * capabilities. Slices created with this function will automatically
+   * have their state saved to storage on every change.
+   */
   createPersistedSlice
 };

src/middleware.ts

@@ -1,9 +1,11 @@
-import { createListenerMiddleware } from "@reduxjs/toolkit";
+import { createListenerMiddleware } from '@reduxjs/toolkit';
 
 /**
- * The single, global instance of the RTK listener middleware.
- * This middleware is used to listen for specific actions and trigger
- * side effects, such as persisting the state to storage.
+ * The core listener middleware for `rtk-persist`.
+ *
+ * This singleton instance is central to the persistence mechanism. It's used
+ * to listen for actions that modify the state of persisted slices and triggers
+ * the side effect of writing those changes to storage.
  *
  * {@link https://redux-toolkit.js.org/api/createListenerMiddleware}
  *