@react-navigation/routers 8.0.0-alpha.1 → 8.0.0-alpha.11

package/src/StackRouter.tsx

@@ -6,7 +6,6 @@ import { createRouteFromAction } from './createRouteFromAction';
 import type {
   CommonNavigationAction,
   DefaultRouterOptions,
-  NavigationRoute,
   NavigationState,
   ParamListBase,
   Route,
@@ -16,36 +15,42 @@ import type {
 export type StackActionType =
   | {
       type: 'REPLACE';
-      payload: { name: string; params?: object };
-      source?: string;
-      target?: string;
+      payload: { name: string; params?: object | undefined };
+      source?: string | undefined;
+      target?: string | undefined;
     }
   | {
       type: 'PUSH';
-      payload: { name: string; params?: object };
-      source?: string;
-      target?: string;
+      payload: { name: string; params?: object | undefined };
+      source?: string | undefined;
+      target?: string | undefined;
     }
   | {
       type: 'POP';
       payload: { count: number };
-      source?: string;
-      target?: string;
+      source?: string | undefined;
+      target?: string | undefined;
     }
   | {
       type: 'POP_TO_TOP';
-      source?: string;
-      target?: string;
+      source?: string | undefined;
+      target?: string | undefined;
     }
   | {
       type: 'POP_TO';
       payload: {
         name: string;
-        params?: object;
-        merge?: boolean;
+        params?: object | undefined;
+        merge?: boolean | undefined;
       };
-      source?: string;
-      target?: string;
+      source?: string | undefined;
+      target?: string | undefined;
+    }
+  | {
+      type: 'RETAIN';
+      payload: { enable: boolean };
+      source?: string | undefined;
+      target?: string | undefined;
     };
 
 export type StackRouterOptions = DefaultRouterOptions;
@@ -57,9 +62,11 @@ export type StackNavigationState<ParamList extends ParamListBase> =
      */
     type: 'stack';
     /**
-     * List of routes, which are supposed to be preloaded before navigating to.
+     * List of route keys to retain in the stack.
+     * When a retained route gets removed from the stack,
+     * it'll be kept in routes and can be navigated to again.
      */
-    preloadedRoutes: NavigationRoute<ParamList, keyof ParamList>[];
+    retainedRouteKeys: string[];
   };
 
 export type StackActionHelpers<ParamList extends ParamListBase> = {
@@ -124,6 +131,15 @@ export type StackActionHelpers<ParamList extends ParamListBase> = {
           ]
       : never
   ): void;
+
+  /**
+   * Enable or disable retaining the current route in the stack.
+   * When a retained route gets removed from the stack,
+   * it'll be kept in routes and can be navigated to again.
+   *
+   * @param enable Whether to retain the current route in the stack or not.
+   */
+  retain(enable: boolean): void;
 };
 
 export const StackActions = {
@@ -158,6 +174,103 @@ export const StackActions = {
       },
     } as const satisfies StackActionType;
   },
+  retain(enable: boolean) {
+    return {
+      type: 'RETAIN',
+      payload: { enable },
+    } as const satisfies StackActionType;
+  },
+};
+
+function retainRoutes<ParamList extends ParamListBase>(
+  previousState: StackNavigationState<ParamList>,
+  nextState: StackNavigationState<ParamList>
+) {
+  if (!nextState.retainedRouteKeys.length) {
+    return nextState;
+  }
+
+  const retainedRouteKeySet = new Set(nextState.retainedRouteKeys);
+  const nextRouteKeySet = new Set(nextState.routes.map((route) => route.key));
+  const retainedRoutes = getActiveRoutes(previousState).filter(
+    (route) =>
+      retainedRouteKeySet.has(route.key) && !nextRouteKeySet.has(route.key)
+  );
+
+  if (!retainedRoutes.length) {
+    return nextState;
+  }
+
+  const removedRetainedRouteKeys = new Set(
+    retainedRoutes.map((route) => route.key)
+  );
+
+  return getStateWithRoutes(
+    nextState,
+    getActiveRoutes(nextState),
+    getPreloadedRoutes(nextState),
+    retainedRoutes.concat(
+      getRetainedRoutes(nextState).filter(
+        (route) => !removedRetainedRouteKeys.has(route.key)
+      )
+    )
+  );
+}
+
+const getActiveRoutes = <ParamList extends ParamListBase>(
+  state: StackNavigationState<ParamList>
+) => state.routes.slice(0, state.index + 1);
+
+const getInactiveRoutes = <ParamList extends ParamListBase>(
+  state: StackNavigationState<ParamList>
+) => state.routes.slice(state.index + 1);
+
+const getPreloadedRoutes = <ParamList extends ParamListBase>(
+  state: StackNavigationState<ParamList>
+) => {
+  const retainedRouteKeySet = new Set(state.retainedRouteKeys);
+
+  return getInactiveRoutes(state).filter(
+    (route) => !retainedRouteKeySet.has(route.key)
+  );
+};
+
+const getRetainedRoutes = <ParamList extends ParamListBase>(
+  state: StackNavigationState<ParamList>
+) => {
+  const retainedRouteKeySet = new Set(state.retainedRouteKeys);
+
+  return getInactiveRoutes(state).filter((route) =>
+    retainedRouteKeySet.has(route.key)
+  );
+};
+
+const getStateWithRoutes = <ParamList extends ParamListBase>(
+  state: StackNavigationState<ParamList>,
+  activeRoutes: Route<string>[],
+  preloadedRoutes = getPreloadedRoutes(state),
+  retainedRoutes = getRetainedRoutes(state)
+) => {
+  const routeKeySet = new Set(activeRoutes.map((route) => route.key));
+  const retainedRouteKeySet = new Set(state.retainedRouteKeys);
+
+  const filteredRetainedRoutes = retainedRoutes.filter(
+    (route) => !routeKeySet.has(route.key)
+  );
+
+  const filteredPreloadedRoutes = preloadedRoutes.filter(
+    (route) =>
+      !retainedRouteKeySet.has(route.key) && !routeKeySet.has(route.key)
+  );
+
+  return {
+    ...state,
+    index: activeRoutes.length - 1,
+    routes: activeRoutes.concat(
+      filteredRetainedRoutes,
+      filteredPreloadedRoutes
+    ),
+  };
 };
 
 export function StackRouter(options: StackRouterOptions) {
@@ -176,13 +289,19 @@ export function StackRouter(options: StackRouterOptions) {
           ? options.initialRouteName
           : routeNames[0];
 
+      if (initialRouteName == null) {
+        throw new Error(
+          "Couldn't initialize the stack navigator. Have you defined any screens?"
+        );
+      }
+
       return {
         stale: false,
         type: 'stack',
         key: `stack-${nanoid()}`,
         index: 0,
         routeNames,
-        preloadedRoutes: [],
+        retainedRouteKeys: [],
         routes: [
           {
             key: `${initialRouteName}-${nanoid()}`,
@@ -214,30 +333,18 @@ export function StackRouter(options: StackRouterOptions) {
               : route.params,
         }));
 
-      const preloadedRoutes =
-        state.preloadedRoutes
-          ?.filter((route) => routeNames.includes(route.name))
-          .map(
-            (route) =>
-              ({
-                ...route,
-                key: route.key || `${route.name}-${nanoid()}`,
-                params:
-                  routeParamList[route.name] !== undefined
-                    ? {
-                        ...routeParamList[route.name],
-                        ...route.params,
-                      }
-                    : route.params,
-              }) as Route<string>
-          ) ?? [];
-
       if (routes.length === 0) {
         const initialRouteName =
           options.initialRouteName !== undefined
             ? options.initialRouteName
             : routeNames[0];
 
+        if (initialRouteName == null) {
+          throw new Error(
+            "Couldn't initialize the stack navigator. Have you defined any screens?"
+          );
+        }
+
         routes.push({
           key: `${initialRouteName}-${nanoid()}`,
           name: initialRouteName,
@@ -245,14 +352,23 @@ export function StackRouter(options: StackRouterOptions) {
         });
       }
 
+      const index = Math.min(
+        Math.max(state.index ?? routes.length - 1, 0),
+        routes.length - 1
+      );
+
+      const routeKeys = new Set(routes.map((route) => route.key));
+      const retainedRouteKeys =
+        state.retainedRouteKeys?.filter((key) => routeKeys.has(key)) ?? [];
+
       return {
         stale: false,
         type: 'stack',
         key: `stack-${nanoid()}`,
-        index: routes.length - 1,
+        index,
         routeNames,
         routes,
-        preloadedRoutes,
+        retainedRouteKeys,
       };
     },
 
@@ -260,7 +376,19 @@ export function StackRouter(options: StackRouterOptions) {
       state,
       { routeNames, routeParamList, routeKeyChanges }
     ) {
-      const routes = state.routes.filter(
+      const routes = getActiveRoutes(state).filter(
+        (route) =>
+          routeNames.includes(route.name) &&
+          !routeKeyChanges.includes(route.name)
+      );
+
+      const preloadedRoutes = getPreloadedRoutes(state).filter(
+        (route) =>
+          routeNames.includes(route.name) &&
+          !routeKeyChanges.includes(route.name)
+      );
+
+      const retainedRoutes = getRetainedRoutes(state).filter(
         (route) =>
           routeNames.includes(route.name) &&
           !routeKeyChanges.includes(route.name)
@@ -273,6 +401,12 @@ export function StackRouter(options: StackRouterOptions) {
             ? options.initialRouteName
             : routeNames[0];
 
+        if (initialRouteName == null) {
+          throw new Error(
+            "Couldn't initialize the stack navigator. Have you defined any screens?"
+          );
+        }
+
         routes.push({
           key: `${initialRouteName}-${nanoid()}`,
           name: initialRouteName,
@@ -280,36 +414,54 @@ export function StackRouter(options: StackRouterOptions) {
         });
       }
 
-      return {
-        ...state,
-        routeNames,
+      const routeKeys = new Set(
+        [...routes, ...preloadedRoutes, ...retainedRoutes].map(
+          (route) => route.key
+        )
+      );
+
+      const retainedRouteKeys = state.retainedRouteKeys.filter((key) =>
+        routeKeys.has(key)
+      );
+
+      return getStateWithRoutes(
+        {
+          ...state,
+          routeNames,
+          retainedRouteKeys,
+        },
         routes,
-        index: Math.min(state.index, routes.length - 1),
-      };
+        preloadedRoutes,
+        retainedRoutes
+      );
     },
 
     getStateForRouteFocus(state, key) {
-      const index = state.routes.findIndex((r) => r.key === key);
+      const routes = getActiveRoutes(state);
+      const index = routes.findIndex((r) => r.key === key);
 
       if (index === -1 || index === state.index) {
         return state;
       }
 
-      return {
-        ...state,
-        index,
-        routes: state.routes.slice(0, index + 1),
-      };
+      return retainRoutes(
+        state,
+        getStateWithRoutes(state, routes.slice(0, index + 1))
+      );
     },
 
     getStateForAction(state, action, options) {
       const { routeParamList } = options;
 
+      const routes = getActiveRoutes(state);
+      const preloadedRoutes = getPreloadedRoutes(state);
+      const inactiveRoutes = getInactiveRoutes(state);
+
       switch (action.type) {
         case 'REPLACE': {
           const currentIndex =
             action.target === state.key && action.source
-              ? state.routes.findIndex((r) => r.key === action.source)
+              ? routes.findIndex((r) => r.key === action.source)
               : state.index;
 
           if (currentIndex === -1) {
@@ -323,8 +475,8 @@ export function StackRouter(options: StackRouterOptions) {
           const getId = options.routeGetIdList[action.payload.name];
           const id = getId?.({ params: action.payload.params });
 
-          // Re-use preloaded route if available
-          let route = state.preloadedRoutes.find(
+          // Re-use inactive route if available
+          let route = inactiveRoutes.find(
             (route) =>
               route.name === action.payload.name &&
               id === getId?.({ params: route.params })
@@ -332,17 +484,22 @@ export function StackRouter(options: StackRouterOptions) {
 
           if (!route) {
             route = createRouteFromAction({ action, routeParamList });
+          } else {
+            const params = createParamsFromAction({ action, routeParamList });
+
+            if (route.params !== params) {
+              route = { ...route, params };
+            }
           }
 
-          return {
-            ...state,
-            routes: state.routes.map((r, i) =>
-              i === currentIndex ? route : r
-            ),
-            preloadedRoutes: state.preloadedRoutes.filter(
-              (r) => r.key !== route.key
-            ),
-          };
+          return retainRoutes(
+            state,
+            getStateWithRoutes(
+              state,
+              routes.map((r, i) => (i === currentIndex ? route : r)),
+              preloadedRoutes.filter((r) => r.key !== route.key)
+            )
+          );
         }
 
         case 'PUSH':
@@ -356,27 +513,79 @@ export function StackRouter(options: StackRouterOptions) {
 
           let route: Route<string> | undefined;
 
-          if (id !== undefined) {
-            route = state.routes.findLast(
-              (route) =>
-                route.name === action.payload.name &&
-                id === getId?.({ params: route.params })
-            );
-          } else if (action.type === 'NAVIGATE') {
-            const currentRoute = state.routes[state.index];
-
-            // If the route matches the current one, then navigate to it
-            if (action.payload.name === currentRoute.name) {
-              route = currentRoute;
-            } else if (action.payload.pop) {
-              route = state.routes.findLast(
-                (route) => route.name === action.payload.name
-              );
+          if (action.type === 'NAVIGATE') {
+            const currentRoute = routes[state.index];
+
+            if (currentRoute == null) {
+              throw new Error(`Couldn't find a route at index ${state.index}.`);
+            }
+
+            if (id !== undefined) {
+              if (
+                currentRoute.name === action.payload.name &&
+                id === getId?.({ params: currentRoute.params })
+              ) {
+                route = currentRoute;
+              } else if (action.payload.pop) {
+                for (let i = routes.length - 1; i >= 0; i--) {
+                  const r = routes[i];
+
+                  if (r == null) {
+                    throw new Error(`Couldn't find a route at index ${i}.`);
+                  }
+
+                  if (r.name !== action.payload.name) {
+                    continue;
+                  }
+
+                  if (id === getId?.({ params: r.params })) {
+                    route = r;
+                    break;
+                  }
+
+                  if (r.history?.length) {
+                    for (let j = r.history.length - 1; j >= 0; j--) {
+                      const historyEntry = r.history[j];
+
+                      if (historyEntry == null) {
+                        throw new Error(
+                          `Couldn't find a route history entry at index ${j}.`
+                        );
+                      }
+
+                      if (
+                        historyEntry.type === 'params' &&
+                        id === getId?.({ params: historyEntry.params })
+                      ) {
+                        route = {
+                          ...r,
+                          params: historyEntry.params,
+                          history: r.history.slice(0, j),
+                        };
+                        break;
+                      }
+                    }
+
+                    if (route) {
+                      break;
+                    }
+                  }
+                }
+              }
+            } else {
+              // If the route matches the current one, then navigate to it
+              if (action.payload.name === currentRoute.name) {
+                route = currentRoute;
+              } else if (action.payload.pop) {
+                route = routes.findLast(
+                  (route) => route.name === action.payload.name
+                );
+              }
             }
           }
 
           if (!route) {
-            route = state.preloadedRoutes.find(
+            route = inactiveRoutes.find(
               (route) =>
                 route.name === action.payload.name &&
                 id === getId?.({ params: route.params })
@@ -399,16 +608,16 @@ export function StackRouter(options: StackRouterOptions) {
             params = createParamsFromAction({ action, routeParamList });
           }
 
-          let routes: Route<string>[];
+          let nextRoutes: Route<string>[];
 
           if (route) {
             if (action.type === 'NAVIGATE' && action.payload.pop) {
-              routes = [];
+              nextRoutes = [];
 
               // Get all routes until the matching one
-              for (const r of state.routes) {
+              for (const r of routes) {
                 if (r.key === route.key) {
-                  routes.push({
+                  nextRoutes.push({
                     ...route,
                     path:
                       action.payload.path !== undefined
@@ -419,11 +628,22 @@ export function StackRouter(options: StackRouterOptions) {
                   break;
                 }
 
-                routes.push(r);
+                nextRoutes.push(r);
+              }
+
+              if (!nextRoutes.some((r) => r.key === route.key)) {
+                nextRoutes.push({
+                  ...route,
+                  path:
+                    action.payload.path !== undefined
+                      ? action.payload.path
+                      : route.path,
+                  params,
+                });
               }
             } else {
-              routes = state.routes.filter((r) => r.key !== route.key);
-              routes.push({
+              nextRoutes = routes.filter((r) => r.key !== route.key);
+              nextRoutes.push({
                 ...route,
                 path:
                   action.type === 'NAVIGATE' &&
@@ -434,8 +654,8 @@ export function StackRouter(options: StackRouterOptions) {
               });
             }
           } else {
-            routes = [
-              ...state.routes,
+            nextRoutes = [
+              ...routes,
               {
                 key: `${action.payload.name}-${nanoid()}`,
                 name: action.payload.name,
@@ -446,23 +666,39 @@ export function StackRouter(options: StackRouterOptions) {
             ];
           }
 
-          return {
-            ...state,
-            index: routes.length - 1,
-            preloadedRoutes: state.preloadedRoutes.filter(
-              (route) => routes[routes.length - 1].key !== route.key
-            ),
-            routes,
-          };
+          const lastRoute = nextRoutes[nextRoutes.length - 1];
+
+          if (lastRoute == null) {
+            throw new Error(
+              `Couldn't find a route at index ${nextRoutes.length - 1}.`
+            );
+          }
+
+          return retainRoutes(
+            state,
+            getStateWithRoutes(
+              state,
+              nextRoutes,
+              preloadedRoutes.filter((route) => lastRoute.key !== route.key)
+            )
+          );
         }
 
         case 'POP': {
           let currentIndex =
             action.target === state.key && action.source
-              ? state.routes.findIndex((r) => r.key === action.source)
+              ? routes.findIndex((r) => r.key === action.source)
               : state.index;
 
-          let route = state.routes[currentIndex];
+          if (currentIndex === -1) {
+            return null;
+          }
+
+          let route = routes[currentIndex];
+
+          if (route == null) {
+            throw new Error(`Couldn't find a route at index ${currentIndex}.`);
+          }
 
           /**
            * When popping entries,
@@ -475,11 +711,11 @@ export function StackRouter(options: StackRouterOptions) {
            */
           if (route.history?.length || currentIndex > 0) {
             let count = action.payload.count;
-            let routes = state.routes;
+            let nextRoutes = routes;
 
             while (count > 0 && (route.history?.length || currentIndex > 0)) {
               if (route.history?.length) {
-                routes = [...routes];
+                nextRoutes = [...nextRoutes];
 
                 const end = Math.min(count, route.history.length);
                 const last = route.history.at(-end);
@@ -488,7 +724,7 @@ export function StackRouter(options: StackRouterOptions) {
 
                 count = count - removed;
 
-                routes[currentIndex] = {
+                nextRoutes[currentIndex] = {
                   ...route,
                   params: last?.type === 'params' ? last.params : route.params,
                   history,
@@ -496,33 +732,42 @@ export function StackRouter(options: StackRouterOptions) {
               }
 
               if (currentIndex > 0 && count > 0) {
-                const length = routes.length;
+                const length = nextRoutes.length;
                 const end = Math.max(currentIndex - count + 1, 1);
 
-                routes = routes
+                nextRoutes = nextRoutes
                   .slice(0, end)
-                  .concat(routes.slice(currentIndex + 1));
+                  .concat(nextRoutes.slice(currentIndex + 1));
 
-                const removed = length - routes.length;
+                const removed = length - nextRoutes.length;
 
                 count = count - removed;
-                currentIndex = routes.length - 1;
-                route = routes[currentIndex];
+                currentIndex = nextRoutes.length - 1;
+
+                const currentRoute = nextRoutes[currentIndex];
+
+                if (currentRoute == null) {
+                  throw new Error(
+                    `Couldn't find a route at index ${currentIndex}.`
+                  );
+                }
+
+                route = currentRoute;
               }
             }
 
-            return {
-              ...state,
-              index: routes.length - 1,
-              routes,
-            };
+            return retainRoutes(state, getStateWithRoutes(state, nextRoutes));
           }
 
           return null;
         }
 
         case 'POP_TO_TOP': {
-          let route = state.routes[0];
+          let route = routes[0];
+
+          if (route == null) {
+            throw new Error("Couldn't find a route at index 0.");
+          }
 
           if (state.index > 0 || route.history?.length) {
             if (route.history?.length) {
@@ -532,11 +777,7 @@ export function StackRouter(options: StackRouterOptions) {
               };
             }
 
-            return {
-              ...state,
-              index: 0,
-              routes: [route],
-            };
+            return retainRoutes(state, getStateWithRoutes(state, [route]));
           }
 
           return null;
@@ -545,7 +786,7 @@ export function StackRouter(options: StackRouterOptions) {
         case 'POP_TO': {
           const currentIndex =
             action.target === state.key && action.source
-              ? state.routes.findLastIndex((r) => r.key === action.source)
+              ? routes.findLastIndex((r) => r.key === action.source)
               : state.index;
 
           if (currentIndex === -1) {
@@ -558,21 +799,76 @@ export function StackRouter(options: StackRouterOptions) {
 
           // If the route already exists, navigate to it
           let index = -1;
+          let historyIndex: number | undefined;
 
           const getId = options.routeGetIdList[action.payload.name];
           const id = getId?.({ params: action.payload.params });
 
           if (id !== undefined) {
-            index = state.routes.findIndex(
-              (route) =>
-                route.name === action.payload.name &&
-                id === getId?.({ params: route.params })
-            );
-          } else if (state.routes[currentIndex].name === action.payload.name) {
-            index = currentIndex;
+            for (let i = currentIndex; i >= 0; i--) {
+              const r = routes[i];
+
+              if (r == null) {
+                throw new Error(`Couldn't find a route at index ${i}.`);
+              }
+
+              if (r.name !== action.payload.name) {
+                continue;
+              }
+
+              if (id === getId?.({ params: r.params })) {
+                index = i;
+                break;
+              }
+
+              if (r.history?.length) {
+                for (let j = r.history.length - 1; j >= 0; j--) {
+                  const historyEntry = r.history[j];
+
+                  if (historyEntry == null) {
+                    throw new Error(
+                      `Couldn't find a route history entry at index ${j}.`
+                    );
+                  }
+
+                  if (
+                    historyEntry.type === 'params' &&
+                    id === getId?.({ params: historyEntry.params })
+                  ) {
+                    index = i;
+                    historyIndex = j;
+                    break;
+                  }
+                }
+
+                if (index !== -1) {
+                  break;
+                }
+              }
+            }
           } else {
+            const currentRoute = routes[currentIndex];
+
+            if (currentRoute == null) {
+              throw new Error(
+                `Couldn't find a route at index ${currentIndex}.`
+              );
+            }
+
+            if (currentRoute.name === action.payload.name) {
+              index = currentIndex;
+            }
+          }
+
+          if (id == null && index === -1) {
             for (let i = currentIndex; i >= 0; i--) {
-              if (state.routes[i].name === action.payload.name) {
+              const route = routes[i];
+
+              if (route == null) {
+                throw new Error(`Couldn't find a route at index ${i}.`);
+              }
+
+              if (route.name === action.payload.name) {
                 index = i;
                 break;
               }
@@ -581,8 +877,8 @@ export function StackRouter(options: StackRouterOptions) {
 
           // If the route doesn't exist, remove the current route and add the new one
           if (index === -1) {
-            // Re-use preloaded route if available
-            let route = state.preloadedRoutes.find(
+            // Re-use inactive route if available
+            let route = inactiveRoutes.find(
               (route) =>
                 route.name === action.payload.name &&
                 id === getId?.({ params: route.params })
@@ -590,21 +886,47 @@ export function StackRouter(options: StackRouterOptions) {
 
             if (!route) {
               route = createRouteFromAction({ action, routeParamList });
+            } else {
+              const params = createParamsFromAction({ action, routeParamList });
+
+              if (route.params !== params) {
+                route = { ...route, params };
+              }
             }
 
-            const routes = state.routes.slice(0, currentIndex).concat(route);
+            const nextRoutes = routes.slice(0, currentIndex).concat(route);
 
-            return {
-              ...state,
-              index: routes.length - 1,
-              routes,
-              preloadedRoutes: state.preloadedRoutes.filter(
-                (r) => r.key !== route.key
-              ),
-            };
+            return retainRoutes(
+              state,
+              getStateWithRoutes(
+                state,
+                nextRoutes,
+                preloadedRoutes.filter((r) => r.key !== route.key)
+              )
+            );
+          }
+
+          const route = routes[index];
+
+          if (route == null) {
+            throw new Error(`Couldn't find a route at index ${index}.`);
           }
 
-          const route = state.routes[index];
+          let baseParams = route.params;
+          let history = route.history;
+
+          if (historyIndex !== undefined && route.history) {
+            const historyEntry = route.history[historyIndex];
+
+            if (historyEntry == null) {
+              throw new Error(
+                `Couldn't find a route history entry at index ${historyIndex}.`
+              );
+            }
+
+            baseParams = historyEntry.params;
+            history = route.history.slice(0, historyIndex);
+          }
 
           let params;
 
@@ -614,28 +936,33 @@ export function StackRouter(options: StackRouterOptions) {
               routeParamList[route.name] !== undefined
                 ? {
                     ...routeParamList[route.name],
-                    ...route.params,
+                    ...baseParams,
                     ...action.payload.params,
                   }
-                : route.params;
+                : baseParams;
           } else {
             params = createParamsFromAction({ action, routeParamList });
           }
 
-          return {
-            ...state,
-            index,
-            routes: [
-              ...state.routes.slice(0, index),
-              params !== route.params
-                ? { ...route, params }
-                : state.routes[index],
-            ],
-          };
+          return retainRoutes(
+            state,
+            getStateWithRoutes(state, [
+              ...routes.slice(0, index),
+              params !== baseParams || historyIndex !== undefined
+                ? { ...route, params, history }
+                : route,
+            ])
+          );
         }
 
-        case 'GO_BACK':
-          if (state.index > 0 || state.routes[state.index].history?.length) {
+        case 'GO_BACK': {
+          const route = routes[state.index];
+
+          if (route == null) {
+            throw new Error(`Couldn't find a route at index ${state.index}.`);
+          }
+
+          if (state.index > 0 || route.history?.length) {
             return router.getStateForAction(
               state,
               {
@@ -649,46 +976,82 @@ export function StackRouter(options: StackRouterOptions) {
           }
 
           return null;
+        }
 
-        case 'PRELOAD': {
-          const getId = options.routeGetIdList[action.payload.name];
-          const id = getId?.({ params: action.payload.params });
+        case 'RETAIN': {
+          const route = routes[state.index];
 
-          let route: Route<string> | undefined;
+          if (route == null) {
+            throw new Error(`Couldn't find a route at index ${state.index}.`);
+          }
 
-          if (id !== undefined) {
-            route = state.routes.find(
-              (route) =>
-                route.name === action.payload.name &&
-                id === getId?.({ params: route.params })
-            );
+          const routeKey = action.source ?? route.key;
+
+          if (!state.routes.some((route) => route.key === routeKey)) {
+            return null;
           }
 
-          if (route) {
+          if (action.payload.enable) {
+            if (state.retainedRouteKeys.includes(routeKey)) {
+              return state;
+            }
+
             return {
               ...state,
-              routes: state.routes.map((r) => {
-                if (r.key !== route?.key) {
-                  return r;
-                }
-                return {
-                  ...r,
-                  params: createParamsFromAction({ action, routeParamList }),
-                };
-              }),
+              retainedRouteKeys: [...state.retainedRouteKeys, routeKey],
             };
-          } else {
-            return {
+          }
+
+          if (!state.retainedRouteKeys.includes(routeKey)) {
+            return state;
+          }
+
+          return getStateWithRoutes(
+            {
               ...state,
-              preloadedRoutes: state.preloadedRoutes
-                .filter(
-                  (r) =>
-                    r.name !== action.payload.name ||
-                    id !== getId?.({ params: r.params })
-                )
-                .concat(createRouteFromAction({ action, routeParamList })),
-            };
+              retainedRouteKeys: state.retainedRouteKeys.filter(
+                (key) => key !== routeKey
+              ),
+            },
+            routes,
+            preloadedRoutes.filter((route) => route.key !== routeKey)
+          );
+        }
+
+        case 'PRELOAD': {
+          if (!state.routeNames.includes(action.payload.name)) {
+            return null;
           }
+
+          const getId = options.routeGetIdList[action.payload.name];
+          const id = getId?.({ params: action.payload.params });
+          const params = createParamsFromAction({ action, routeParamList });
+
+          const route = preloadedRoutes.findLast(
+            (route) =>
+              route.name === action.payload.name &&
+              (id === undefined || id === getId?.({ params: route.params }))
+          );
+
+          if (route) {
+            return getStateWithRoutes(
+              state,
+              routes,
+              preloadedRoutes.map((r) =>
+                r.key === route.key && r.params !== params
+                  ? { ...r, params }
+                  : r
+              )
+            );
+          }
+
+          return getStateWithRoutes(
+            state,
+            routes,
+            preloadedRoutes.concat(
+              createRouteFromAction({ action, routeParamList })
+            )
+          );
         }
 
         default:
@@ -696,10 +1059,6 @@ export function StackRouter(options: StackRouterOptions) {
       }
     },
 
-    getRoutesFromState(state) {
-      return [...state.routes, ...state.preloadedRoutes];
-    },
-
     actionCreators: StackActions,
   };