Update nesting support

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, RehydrateActionPayload } from './types';
+import { NestedPath, NotFunction, PersistedReducer, RehydrateActionPayload } from './types';
 import UpdatedAtHelper from './updatedAtHelper';
-import { REHYDRATE, writePersistedStorage } from './utils';
+import { deepGetByPath, REHYDRATE, writePersistedStorage } from './utils';
 
 /**
  * A utility function that creates a persisted reducer. It wraps the standard
@@ -24,6 +24,7 @@ import { REHYDRATE, writePersistedStorage } from './utils';
  * @param reducerName - A unique string name for the reducer. This name is used as the key in the root state object and for storage.
  * @param initialState - The initial state for the reducer. Can be a value or a lazy initializer function.
  * @param mapOrBuilderCallback - A callback that receives a `builder` object to define case reducers via `builder.addCase`, `builder.addMatcher`, and `builder.addDefaultCase`.
+ * @param nesting - An optional dot-separated string path indicating where the reducer is nested within the root state.
  * @example
 ```ts
 import {
@@ -64,24 +65,28 @@ const reducer = createPersistedReducer(
 ```
  * @public
  */
-export const createPersistedReducer: <
+export const createPersistedReducer = <
   ReducerName extends string,
-  S extends NotFunction<any>
+  S extends NotFunction<any>,
+  Nesting extends string | undefined = undefined
 >(
   reducerName: ReducerName,
   initialState: S | (() => S),
   mapOrBuilderCallback: (builder: ActionReducerMapBuilder<S>) => void,
-) => ReducerWithInitialState<S> = <ReducerName extends string, S extends NotFunction<any>>(
-  reducerName: ReducerName,
-  initialState: S | (() => S),
-  mapOrBuilderCallback: (builder: ActionReducerMapBuilder<S>) => void,
-) => {
+  nesting?: Nesting,
+): PersistedReducer<S, ReducerName, Nesting> => {
   /**
    * 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);
 
+  /**
+   * The full dot-separated path to the slice's state within the root state object.
+   * @internal
+   */
+  const nestedPath = (nesting && nesting !== '' ? `${nesting}.${reducerName}` : reducerName) as NestedPath<ReducerName, Nesting>;
+
   /**
    * A timeout variable to manage the debouncing of the storage write.
    * @internal
@@ -94,10 +99,11 @@ export const createPersistedReducer: <
    * @param state - The current root state of the Redux store.
    * @internal
    */
-  const onDump = (state: Record<ReducerName, S>) => {
+  const onDump = (state: Record<string, any>) => {
     if (debounceTimeout) clearTimeout(debounceTimeout);
     debounceTimeout = setTimeout(() => {
-      writePersistedStorage(state[reducerName], reducerName);
+      const [reducerState] = deepGetByPath(state, nestedPath);
+      writePersistedStorage(reducerState, reducerName);
     }, 100);
   };
 
@@ -106,9 +112,7 @@ export const createPersistedReducer: <
    * @internal
    */
   const startAppListening =
-    listenerMiddleware.startListening.withTypes<
-      Record<ReducerName, S>
-    >();
+    listenerMiddleware.startListening.withTypes<Record<string, any>>();
 
   /**
    * Creates the main reducer, extending the builder to track state changes
@@ -122,7 +126,7 @@ export const createPersistedReducer: <
     });
     const b = new Builder(builder, UpdatedAtHelper.onStateChange.bind(null, reducerName));
     mapOrBuilderCallback(b);
-  }) as ReducerWithInitialState<S>;
+  });
 
   /**
    * Listens for any action (except rehydration) to check if the state
@@ -151,13 +155,10 @@ export const createPersistedReducer: <
     effect: () => UpdatedAtHelper.onSave(reducerName),
   });
 
-  /**
-   * Attaches the unique reducer name to the reducer function itself.
-   * This allows other parts of the persistence logic to identify the reducer
-   * and its corresponding state slice.
-   * @public
-   */
-  reducer.reducerName = reducerName;
-
-  return reducer;
+  // This is the cleanest way to construct the final object and apply the
+  // necessary type assertion once.
+  return Object.assign(reducer, {
+    reducerName,
+    nestedPath,
+  }) as PersistedReducer<S, ReducerName, Nesting>;
 };

src/slice.ts

@@ -2,16 +2,15 @@ import {
   createSlice,
   CreateSliceOptions,
   PayloadAction,
-  Slice,
   SliceCaseReducers,
   SliceSelectors
 } from '@reduxjs/toolkit';
 import { Builder } from './extraReducersBuilder';
 import { listenerMiddleware } from './middleware';
 import Settings from './settings';
-import { RehydrateActionPayload } from './types';
+import { NestedPath, PersistedSlice, RehydrateActionPayload } from './types';
 import UpdatedAtHelper from './updatedAtHelper';
-import { REHYDRATE, writePersistedStorage } from './utils';
+import { deepGetByPath, REHYDRATE, writePersistedStorage } from './utils';
 
 /**
  * A wrapper around the standard RTK `createSlice()` function that adds
@@ -21,18 +20,18 @@ import { REHYDRATE, writePersistedStorage } from './utils';
  * This function requires the use of {@link configurePersistedStore}.
  *
  * @param sliceOptions - The standard `CreateSliceOptions` object from Redux Toolkit.
- * @returns A Redux slice object with persistence enabled.
+ * @param nesting - An optional dot-separated string path indicating where the slice is nested within the root state.
+ * @returns A Redux slice object with persistence enabled, enhanced with a `nestedPath` property that has a correctly inferred literal type.
  *
  * @public
  */
-export const createPersistedSlice: <
+export const createPersistedSlice = <
   SliceState,
-  Name extends string = string,
-  PCR extends
-    SliceCaseReducers<SliceState> = SliceCaseReducers<SliceState>,
+  Name extends string,
+  PCR extends SliceCaseReducers<SliceState>,
   ReducerPath extends string = Name,
-  PeristedSelectors extends
-    SliceSelectors<SliceState> = SliceSelectors<SliceState>,
+  PeristedSelectors extends SliceSelectors<SliceState> = SliceSelectors<SliceState>,
+  Nesting extends string | undefined = undefined
 >(
   sliceOptions: CreateSliceOptions<
     SliceState,
@@ -41,29 +40,21 @@ export const createPersistedSlice: <
     ReducerPath,
     PeristedSelectors
   >,
-) => Slice<SliceState, PCR, Name, ReducerPath, PeristedSelectors> = <
-  SliceState,
-  Name extends string = string,
-  PCR extends
-    SliceCaseReducers<SliceState> = SliceCaseReducers<SliceState>,
-  ReducerPath extends string = Name,
-  PeristedSelectors extends
-    SliceSelectors<SliceState> = SliceSelectors<SliceState>,
->(
-  sliceOptions: CreateSliceOptions<
-    SliceState,
-    PCR,
-    Name,
-    ReducerPath,
-    PeristedSelectors
-  >,
-) => {
+  nesting?: Nesting,
+): PersistedSlice<SliceState, PCR, Name, ReducerPath, PeristedSelectors, Nesting> => {
   /**
    * 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);
 
+  const name = sliceOptions.reducerPath ?? sliceOptions.name;
+  /**
+   * The full dot-separated path to the slice's state within the root state object.
+   * @internal
+   */
+  const nestedPath = (nesting && nesting !== '' ? `${nesting}.${name}` : name) as NestedPath<ReducerPath, Nesting>;
+
   /**
    * A timeout variable to manage the debouncing of the storage write.
    * @internal
@@ -76,10 +67,12 @@ export const createPersistedSlice: <
    * @param state - The current root state of the Redux store.
    * @internal
    */
-  const onDump = (state: Record<Name | ReducerPath, SliceState>) => {
+  const onDump = (state: Record<string, any>) => {
     if (debounceTimeout) clearTimeout(debounceTimeout);
     debounceTimeout = setTimeout(() => {
-      writePersistedStorage(state[sliceOptions.reducerPath ?? sliceOptions.name], sliceOptions.name);
+      // Use deepGetByPath with the single correct path
+      const sliceState = deepGetByPath(state, nestedPath);
+      writePersistedStorage(sliceState, sliceOptions.name);
     }, 100);
   };
 
@@ -88,9 +81,7 @@ export const createPersistedSlice: <
    * @internal
    */
   const startAppListening =
-    listenerMiddleware.startListening.withTypes<
-      Record<Name | ReducerPath, SliceState>
-    >();
+    listenerMiddleware.startListening.withTypes<Record<string, any>>();
 
   /**
    * Creates the slice using the default options passed by the user,
@@ -118,7 +109,7 @@ export const createPersistedSlice: <
   Object.keys(slice.actions).forEach(type => {
     startAppListening({
       type: `${slice.name}/${type}`,
-      effect: (_action, { getState,  }) => {
+      effect: (_action, { getState }) => {
         const state = getState();
         onDump(state);
       },
@@ -152,5 +143,5 @@ export const createPersistedSlice: <
     effect: () => UpdatedAtHelper.onSave(sliceOptions.name),
   });
 
-  return slice;
+  return { ...slice, nestedPath };
 };

src/store.ts

@@ -137,12 +137,10 @@ export const configurePersistedStore: <
   persistedStore.replaceReducer = (nR) => {
     _replaceReducer.call(persistedStore, nR);
     rehydrate();
-  }
+  };
 
   // Asynchronously trigger the initial rehydration.
   rehydrate();
 
-
-
   return { ...persistedStore, rehydrate, clearPersistedState };
 }

src/types.ts

@@ -6,6 +6,9 @@ import {
   Middleware,
   Reducer,
   SerializableStateInvariantMiddlewareOptions,
+  Slice,
+  SliceCaseReducers,
+  SliceSelectors,
   StoreEnhancer,
   ThunkMiddleware,
   Tuple,
@@ -86,13 +89,48 @@ export type ExtractDispatchExtensions<M> = M extends Tuple<infer MiddlewareTuple
 export type NotFunction<T> = T extends Function ? never : T;
 
 /**
- * A utility type that enhances a Redux reducer with properties needed for persistence,
- * such as its name and a function to get its initial state.
+ * A conditional type that constructs the full dot-notation path for a nested slice or reducer.
+ * If `Nesting` is undefined or an empty string, it returns the `ReducerPath` directly.
+ * Otherwise, it prepends the nesting path.
+ *
+ * @internal
+ */
+export type NestedPath<
+  ReducerPath extends string,
+  Nesting extends string | undefined
+> = Nesting extends '' | undefined
+    ? ReducerPath
+    : `${NonNullable<Nesting>}.${ReducerPath}`
+
+/**
+ * A utility type that enhances a Redux reducer with properties needed for persistence.
+ * It adds `reducerName` and the calculated `nestedPath` to the standard reducer type.
+ * @internal
+ */
+export type PersistedReducer<
+  S extends NotFunction<any>,
+  ReducerName extends string,
+  Nesting extends string | undefined
+> = Reducer<S> & {
+  reducerName: ReducerName;
+  nestedPath: NestedPath<ReducerName, Nesting>;
+};
+
+/**
+ * A utility type that enhances a Redux slice with the `nestedPath` property,
+ * which represents its full path within the root state.
+ *
  * @internal
  */
-export interface ReducerWithInitialState<S extends NotFunction<any>> extends Reducer<S> {
-  getInitialState: () => S;
-  reducerName: string;
+export type PersistedSlice<
+  SliceState,
+  PCR extends SliceCaseReducers<SliceState>,
+  Name extends string,
+  ReducerPath extends string,
+  PeristedSelectors extends SliceSelectors<SliceState>,
+  Nesting extends string | undefined
+> = Slice<SliceState, PCR, Name, ReducerPath, PeristedSelectors> & {
+  nestedPath: NestedPath<ReducerPath, Nesting>;
 };
 
 /**

src/utils.ts

@@ -76,3 +76,72 @@ export async function clearPersistedStorage(name: string) {
   const storageName = getStorageName(name);
   await Settings.storageHandler.removeItem(storageName);
 }
+
+/**
+ * Safely retrieves a nested value from an object using an array of keys.
+ * It traverses the object according to the sequence of keys provided.
+ *
+ * @param obj The object to query. Can be of any type, but functions correctly with nested objects and arrays.
+ * @param keys An array of strings or numbers representing the path to the desired value.
+ * @returns The nested value if found, otherwise null if the path is invalid or the value is null/undefined.
+ */
+export const deepGet = <Name extends string = string>(obj: any, keys: (Name)[]): any => {
+  return keys.reduce((xs, x) => (xs?.[x] !== undefined && xs?.[x] !== null) ? xs[x] : null, obj);
+};
+
+/**
+ * Retrieves multiple nested values from an object based on string paths.
+ * It supports both dot notation (e.g., 'prop1.prop2') and bracket notation for array access (e.g., 'prop1[0]').
+ *
+ * @param obj The object to query.
+ * @param paths A rest parameter of string paths to retrieve values for.
+ * @returns An array containing the retrieved values. If a path is not found, the corresponding value in the array will be null.
+ */
+export const deepGetByPath = (obj: any, path: string): any => {
+  // Convert bracket notation to dot notation, then split into an array of keys.
+  const keys = path
+    .replace(/\[([^\[\]]*)\]/g, '.$1.')
+    .split('.')
+    .filter(t => t !== ''); // Filter out empty strings that may arise from the regex replacement.
+
+  return deepGet(obj, keys);
+};
+
+/**
+ * A helper type to identify primitive values that the recursive
+ * path generation should not traverse into.
+ */
+type Primitive = string | number | boolean | null | undefined;
+
+/**
+ * Creates a union of all possible dot-notation paths for a given object type T.
+ * This is useful for creating strongly-typed functions that access nested
+ * properties of an object like a Redux state. An empty string is also considered a valid path.
+ *
+ * @example
+ * type MyState = { user: { name: string }, posts: { id: number }[] }
+ * type MyStatePaths = Paths<MyState>
+ * // "" | "user" | "user.name" | "posts" | `posts.${number}` | `posts.${number}.id`
+ */
+export type Paths<T> = "" | (T extends Primitive
+  ? never // Base case: Don't generate paths for primitive types.
+  : T extends (infer U)[]
+  ? `${number}` | `${number}.${Paths<U>}` // Handle array paths with numeric indices.
+  : {
+      // For each key in the object...
+      [K in keyof T & string]: T[K] extends Primitive
+        ? K // If the property is primitive, the path is just the key.
+        : K | `${K}.${Paths<T[K]>}`; // Otherwise, recurse into the nested object.
+    }[keyof T & string]); // Create a union of all the generated path strings.
+
+/**
+ * A strongly-typed path validation function for a given state object type.
+ * This function doesn't do anything at runtime; its purpose is to provide
+ * compile-time feedback (linter errors) for invalid paths.
+ *
+ * @param path A path that must be a valid key path within the generic type T.
+ */
+export const createStatePathValidator = <T extends object>(_path: Paths<T>): void => {
+  // This function is intentionally empty. Its sole purpose is to enforce
+  // type-checking on the 'path' argument at compile time.
+};