Update documentation and add dump debounce

Author: tommasoberlose

src/reducer.ts

@@ -6,9 +6,9 @@ import {
 import { Builder } from './extraReducersBuilder';
 import { listenerMiddleware } from './middleware';
 import Settings from './settings';
-import { NotFunction, ReducerWithInitialState, REHYDRATE } from './types';
+import { NotFunction, ReducerWithInitialState } from './types';
 import UpdatedAtHelper from './updatedAtHelper';
-import { writePersistedStorage } from './utils';
+import { REHYDRATE, writePersistedStorage } from './utils';
 
 /**
  * A utility function that creates a persisted reducer. It wraps the standard
@@ -76,14 +76,38 @@ export const createPersistedReducer: <
   initialState: S | (() => S),
   mapOrBuilderCallback: (builder: ActionReducerMapBuilder<S>) => void,
 ) => {
-  // Subscribe the reducer to be persisted
+  /**
+   * Registers the reducer's name to the list of persisted slices.
+   * This allows the persistence logic to identify which parts of the state to manage.
+   */
   Settings.subscribeSlice(reducerName);
+
   /**
    * A flag to ensure the rehydration process runs only once.
    * @internal
    */
   let isHydrated = false;
 
+  /**
+   * A timeout variable to manage the debouncing of the storage write.
+   * @internal
+   */
+  let debounceTimeout: NodeJS.Timeout | null = null;
+
+  /**
+   * Debounces the `writePersistedStorage` function to prevent excessive writes
+   * during rapid state changes. The state is saved 100ms after the last change.
+   * @param state - The current root state of the Redux store.
+   * @param name - The name of the slice to persist.
+   * @internal
+   */
+  const onDump = (state: Record<ReducerName, S>, name: ReducerName) => {
+    if (debounceTimeout) clearTimeout(debounceTimeout);
+    debounceTimeout = setTimeout(() => {
+      writePersistedStorage(state, name);
+    }, 100);
+  };
+
   /**
    * Creates a typed instance of the listener middleware's startListening function.
    * @internal
@@ -117,13 +141,13 @@ export const createPersistedReducer: <
   startAppListening({
     predicate: (action) => {
       // Exclude the rehydrate action from triggering a save.
-      if (action.type === REHYDRATE.toString()) return false;
+      if (action.type === REHYDRATE.toString() || !Settings.isPersistenceEnabled) return false;
       return true;
     },
     effect: async (_action, { getState }) => {
-      if (!await UpdatedAtHelper.shouldSave(reducerName) || !Settings.isPersistenceEnabled) return;
+      if (!await UpdatedAtHelper.shouldSave(reducerName)) return;
       const state = getState();
-      writePersistedStorage(state, reducerName);
+      onDump(state, reducerName);
     },
   });
 

src/slice.ts

@@ -9,9 +9,8 @@ import {
 import { Builder } from './extraReducersBuilder';
 import { listenerMiddleware } from './middleware';
 import Settings from './settings';
-import { REHYDRATE } from './types';
 import UpdatedAtHelper from './updatedAtHelper';
-import { writePersistedStorage } from './utils';
+import { REHYDRATE, writePersistedStorage } from './utils';
 
 /**
  * A wrapper around the standard RTK `createSlice()` function that adds
@@ -58,14 +57,38 @@ export const createPersistedSlice: <
     PeristedSelectors
   >,
 ) => {
-  // Subscribe the slice to be persisted
+  /**
+   * Registers the slice's name to the list of persisted slices.
+   * This allows the persistence logic to identify which parts of the state to manage.
+   */
   Settings.subscribeSlice(sliceOptions.name);
+
   /**
    * A flag to ensure the rehydration process runs only once per slice.
    * @internal
    */
   let isHydrated = false;
 
+  /**
+   * A timeout variable to manage the debouncing of the storage write.
+   * @internal
+   */
+  let debounceTimeout: NodeJS.Timeout | null = null;
+
+  /**
+   * Debounces the `writePersistedStorage` function to prevent excessive writes
+   * during rapid state changes. The state is saved 100ms after the last change.
+   * @param state - The current root state of the Redux store.
+   * @param name - The name of the slice to persist.
+   * @internal
+   */
+  const onDump = (state: Record<Name, SliceState>, name: Name) => {
+    if (debounceTimeout) clearTimeout(debounceTimeout);
+    debounceTimeout = setTimeout(() => {
+      writePersistedStorage(state, name);
+    }, 100);
+  };
+
   /**
    * Creates a typed instance of the listener middleware's startListening function.
    * @internal
@@ -106,7 +129,7 @@ export const createPersistedSlice: <
       effect: (_action, { getState }) => {
         if (Settings.isPersistenceEnabled) {
           const state = getState();
-          writePersistedStorage(state, sliceOptions.name);
+          onDump(state, sliceOptions.name);
         }
       },
     });
@@ -120,13 +143,13 @@ export const createPersistedSlice: <
   startAppListening({
     predicate: (action) => {
       // Exclude the slice's own actions (already handled) and the rehydrate action.
-      if (action.type === REHYDRATE.toString() || action.type.startsWith(`${slice.name}/`)) return false;
+      if (action.type === REHYDRATE.toString() || action.type.startsWith(`${slice.name}/`) || !Settings.isPersistenceEnabled) return false;
       return true;
     },
     effect: async (_action, { getState }) => {
-      if (!await UpdatedAtHelper.shouldSave(sliceOptions.name) || !Settings.isPersistenceEnabled) return;
+      if (!await UpdatedAtHelper.shouldSave(sliceOptions.name)) return;
       const state = getState();
-      writePersistedStorage(state, sliceOptions.name);
+      onDump(state, sliceOptions.name);
     },
   });
 

src/store.ts

@@ -1,9 +1,9 @@
 import { Action, configureStore, ConfigureStoreOptions, createDynamicMiddleware, createListenerMiddleware, StoreEnhancer, Tuple, UnknownAction } from "@reduxjs/toolkit";
 import { listenerMiddleware } from "./middleware";
 import Settings from "./settings";
-import { Enhancers, ExtractDispatchExtensions, Middlewares, PersistedStore, REHYDRATE, RESUME_PERSISTANCE, StorageHandler, ThunkMiddlewareFor } from "./types";
+import { Enhancers, ExtractDispatchExtensions, Middlewares, PersistedStore, StorageHandler, ThunkMiddlewareFor } from "./types";
 import UpdatedAtHelper from "./updatedAtHelper";
-import { clearPersistedStorage, getStoredState } from "./utils";
+import { clearPersistedStorage, getStoredState, REHYDRATE, RESUME_PERSISTANCE } from "./utils";
 
 /**
  * A friendly encapsulation of the standard RTK `configureStore()` function

src/types.ts

@@ -1,7 +1,6 @@
 import {
   Action,
   ActionCreatorInvariantMiddlewareOptions,
-  createAction,
   EnhancedStore,
   ImmutableStateInvariantMiddlewareOptions,
   Middleware,
@@ -35,19 +34,6 @@ export interface StorageHandler {
   removeItem: (key: string) => Promise<void> | void;
 }
 
-/**
- * Action dispatched to rehydrate the store with persisted state.
- * @internal
- */
-export const REHYDRATE = createAction<Record<string, unknown>>('@@INIT-PERSIST');
-
-/**
- * Action dispatched to trigger an immediate re-save of the current state
- * after persistence has been resumed.
- * @internal
- */
-export const RESUME_PERSISTANCE = createAction<void>('@@RESUME-PERSIST');
-
 // --- Internal RTK Types ---
 // These types are re-exported or re-defined from Redux Toolkit's internal
 // types to ensure proper type inference in `configurePersistedStore`.

src/utils.ts

@@ -1,6 +1,20 @@
+import { createAction } from "@reduxjs/toolkit";
 import Settings from "./settings";
 import UpdatedAtHelper from "./updatedAtHelper";
 
+/**
+ * Action dispatched to rehydrate the store with persisted state.
+ * @internal
+ */
+export const REHYDRATE = createAction<Record<string, unknown>>('@@INIT-PERSIST');
+
+/**
+ * Action dispatched to trigger an immediate re-save of the current state
+ * after persistence has been resumed.
+ * @internal
+ */
+export const RESUME_PERSISTANCE = createAction<void>('@@RESUME-PERSIST');
+
 /**
  * Generates the unique storage key for a given slice name.
  * @param name - The name of the slice.