@react-navigation/routers 8.0.0-alpha.2 → 8.0.0-alpha.20

package/src/StackRouter.tsx

@@ -6,7 +6,6 @@ import { createRouteFromAction } from './createRouteFromAction';
 import type {
   CommonNavigationAction,
   DefaultRouterOptions,
-  NavigationRoute,
   NavigationState,
   ParamListBase,
   Route,
@@ -16,36 +15,48 @@ 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;
+    }
+  | {
+      type: 'DISMISS';
+      payload: { count: number };
+      source?: string | undefined;
+      target?: string | undefined;
     };
 
 export type StackRouterOptions = DefaultRouterOptions;
@@ -57,14 +68,16 @@ 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> = {
   /**
-   * Replace the current route with a new one.
+   * Replace the current screen with a new one.
    *
    * @param screen Name of the new route that will replace the current one.
    * @param [params] Params object for the new route.
@@ -92,12 +105,15 @@ export type StackActionHelpers<ParamList extends ParamListBase> = {
   ): void;
 
   /**
-   * Pop a screen from the stack.
+   * Pop a history entry from the stack.
+   * Also dismisses any screens above the current one.
+   *
+   * @param [count=1] Number of history entries to pop. Defaults to 1.
    */
   pop(count?: number): void;
 
   /**
-   * Pop to the first route in the stack, dismissing all other screens.
+   * Pop to the first screen in the stack, dismissing all other screens.
    */
   popToTop(): void;
 
@@ -115,15 +131,32 @@ export type StackActionHelpers<ParamList extends ParamListBase> = {
         ? [
             screen: RouteName,
             params?: ParamList[RouteName],
-            options?: { merge?: boolean },
+            options?: { merge?: boolean | undefined },
           ]
         : [
             screen: RouteName,
             params: ParamList[RouteName],
-            options?: { merge?: boolean },
+            options?: { merge?: boolean | undefined },
           ]
       : never
   ): void;
+
+  /**
+   * Enable or disable retaining the current screen 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;
+
+  /**
+   * Dismiss a screen from the stack.
+   *
+   * @param [count=1] Number of screens to dismiss. Defaults to 1.
+   */
+  dismiss(count?: number): void;
 };
 
 export const StackActions = {
@@ -148,7 +181,11 @@ export const StackActions = {
   popToTop() {
     return { type: 'POP_TO_TOP' } as const satisfies StackActionType;
   },
-  popTo(name: string, params?: object, options?: { merge?: boolean }) {
+  popTo(
+    name: string,
+    params?: object,
+    options?: { merge?: boolean | undefined }
+  ) {
     return {
       type: 'POP_TO',
       payload: {
@@ -158,6 +195,109 @@ export const StackActions = {
       },
     } as const satisfies StackActionType;
   },
+  retain(enable: boolean) {
+    return {
+      type: 'RETAIN',
+      payload: { enable },
+    } as const satisfies StackActionType;
+  },
+  dismiss(count: number = 1) {
+    return {
+      type: 'DISMISS',
+      payload: { count },
+    } 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 +316,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 +360,19 @@ 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 !== undefined &&
+          routeNames.includes(options.initialRouteName)
             ? 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 +380,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 +404,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 +429,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,51 +442,73 @@ 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 activeRoutes = getActiveRoutes(state);
 
-      if (index === -1 || index === state.index) {
+      const route = state.routes.find((route) => route.key === key);
+
+      if (route == null || route === activeRoutes.at(-1)) {
         return state;
       }
 
-      return {
-        ...state,
-        index,
-        routes: state.routes.slice(0, index + 1),
-      };
+      const index = activeRoutes.indexOf(route);
+      const routes =
+        index === -1
+          ? activeRoutes.concat(route)
+          : activeRoutes.slice(0, index + 1);
+
+      return retainRoutes(state, getStateWithRoutes(state, routes));
     },
 
     getStateForAction(state, action, options) {
       const { routeParamList } = options;
 
+      const routes = getActiveRoutes(state);
+      const preloadedRoutes = getPreloadedRoutes(state);
+      const inactiveRoutes = getInactiveRoutes(state);
+
       switch (action.type) {
         case 'REPLACE': {
+          if (!state.routeNames.includes(action.payload.name)) {
+            return null;
+          }
+
           const currentIndex =
-            action.target === state.key && action.source
-              ? state.routes.findIndex((r) => r.key === action.source)
+            action.source !== undefined
+              ? routes.findIndex((r) => r.key === action.source)
               : state.index;
 
           if (currentIndex === -1) {
             return null;
           }
 
-          if (!state.routeNames.includes(action.payload.name)) {
-            return null;
-          }
-
           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 +516,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':
@@ -354,20 +543,41 @@ export function StackRouter(options: StackRouterOptions) {
           const getId = options.routeGetIdList[action.payload.name];
           const id = getId?.({ params: action.payload.params });
 
+          let remainingRoutes = routes;
           let route: Route<string> | undefined;
 
           if (action.type === 'NAVIGATE') {
-            const currentRoute = state.routes[state.index];
+            const currentIndex =
+              action.source !== undefined
+                ? routes.findIndex((r) => r.key === action.source)
+                : 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 = state.routes.length - 1; i >= 0; i--) {
-                  const r = state.routes[i];
+            if (currentIndex === -1) {
+              return null;
+            }
+
+            /**
+             * When navigating,
+             * - If the current route matches the destination, reuse it.
+             * - Or, if a route matching the destination exists after the current, reuse it.
+             * - Remove all non-matching routes after the current.
+             */
+            remainingRoutes = routes.slice(0, currentIndex + 1);
+            route = routes.find(
+              (route, i) =>
+                i >= currentIndex &&
+                route.name === action.payload.name &&
+                (id === undefined || id === getId?.({ params: route.params }))
+            );
+
+            if (!route && action.payload.pop) {
+              if (id !== undefined) {
+                for (let i = remainingRoutes.length - 1; i >= 0; i--) {
+                  const r = remainingRoutes[i];
+
+                  if (r == null) {
+                    throw new Error(`Couldn't find a route at index ${i}.`);
+                  }
 
                   if (r.name !== action.payload.name) {
                     continue;
@@ -380,13 +590,21 @@ export function StackRouter(options: StackRouterOptions) {
 
                   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 (
-                        r.history[j].type === 'params' &&
-                        id === getId?.({ params: r.history[j].params })
+                        historyEntry.type === 'params' &&
+                        id === getId?.({ params: historyEntry.params })
                       ) {
                         route = {
                           ...r,
-                          params: r.history[j].params,
+                          params: historyEntry.params,
                           history: r.history.slice(0, j),
                         };
                         break;
@@ -398,13 +616,8 @@ export function StackRouter(options: StackRouterOptions) {
                     }
                   }
                 }
-              }
-            } 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 = state.routes.findLast(
+              } else {
+                route = remainingRoutes.findLast(
                   (route) => route.name === action.payload.name
                 );
               }
@@ -412,7 +625,7 @@ export function StackRouter(options: StackRouterOptions) {
           }
 
           if (!route) {
-            route = state.preloadedRoutes.find(
+            route = inactiveRoutes.find(
               (route) =>
                 route.name === action.payload.name &&
                 id === getId?.({ params: route.params })
@@ -435,43 +648,35 @@ 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) {
+              // Get all routes before the matching one
+              for (const r of remainingRoutes) {
                 if (r.key === route.key) {
-                  routes.push({
-                    ...route,
-                    path:
-                      action.payload.path !== undefined
-                        ? action.payload.path
-                        : route.path,
-                    params,
-                  });
                   break;
                 }
 
-                routes.push(r);
+                nextRoutes.push(r);
               }
             } else {
-              routes = state.routes.filter((r) => r.key !== route.key);
-              routes.push({
-                ...route,
-                path:
-                  action.type === 'NAVIGATE' &&
-                  action.payload.path !== undefined
-                    ? action.payload.path
-                    : route.path,
-                params,
-              });
+              nextRoutes = remainingRoutes.filter((r) => r.key !== route.key);
             }
+
+            nextRoutes.push({
+              ...route,
+              path:
+                action.type === 'NAVIGATE' && action.payload.path !== undefined
+                  ? action.payload.path
+                  : route.path,
+              params,
+            });
           } else {
-            routes = [
-              ...state.routes,
+            nextRoutes = [
+              ...remainingRoutes,
               {
                 key: `${action.payload.name}-${nanoid()}`,
                 name: action.payload.name,
@@ -482,41 +687,41 @@ export function StackRouter(options: StackRouterOptions) {
             ];
           }
 
-          return {
-            ...state,
-            index: routes.length - 1,
-            preloadedRoutes: state.preloadedRoutes.filter(
-              (route) => routes[routes.length - 1].key !== route.key
-            ),
-            routes,
-          };
+          return retainRoutes(state, getStateWithRoutes(state, nextRoutes));
         }
 
         case 'POP': {
           let currentIndex =
-            action.target === state.key && action.source
-              ? state.routes.findIndex((r) => r.key === action.source)
+            action.source !== undefined
+              ? 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,
            * - Pop entries from route.history
-           * - Pop routes from state.routes
+           * - Pop the route itself and continue from the route below it
            *
            * Repeat until:
            * - We have popped the amount of items in count
            * - There are no more items to pop
+           *
+           * Routes above the current route are removed.
            */
           if (route.history?.length || currentIndex > 0) {
             let count = action.payload.count;
-            let routes = state.routes;
 
             while (count > 0 && (route.history?.length || currentIndex > 0)) {
               if (route.history?.length) {
-                routes = [...routes];
-
                 const end = Math.min(count, route.history.length);
                 const last = route.history.at(-end);
                 const history = route.history.slice(0, -end);
@@ -524,7 +729,7 @@ export function StackRouter(options: StackRouterOptions) {
 
                 count = count - removed;
 
-                routes[currentIndex] = {
+                route = {
                   ...route,
                   params: last?.type === 'params' ? last.params : route.params,
                   history,
@@ -532,33 +737,70 @@ export function StackRouter(options: StackRouterOptions) {
               }
 
               if (currentIndex > 0 && count > 0) {
-                const length = routes.length;
-                const end = Math.max(currentIndex - count + 1, 1);
+                count = count - 1;
+                currentIndex = currentIndex - 1;
 
-                routes = routes
-                  .slice(0, end)
-                  .concat(routes.slice(currentIndex + 1));
+                const currentRoute = routes[currentIndex];
 
-                const removed = length - routes.length;
+                if (currentRoute == null) {
+                  throw new Error(
+                    `Couldn't find a route at index ${currentIndex}.`
+                  );
+                }
 
-                count = count - removed;
-                currentIndex = routes.length - 1;
-                route = routes[currentIndex];
+                route = currentRoute;
               }
             }
 
-            return {
-              ...state,
-              index: routes.length - 1,
-              routes,
-            };
+            const nextRoutes = routes.slice(0, currentIndex + 1);
+
+            if (route !== routes[currentIndex]) {
+              nextRoutes[currentIndex] = route;
+            }
+
+            return retainRoutes(state, getStateWithRoutes(state, nextRoutes));
           }
 
           return null;
         }
 
+        case 'DISMISS': {
+          const currentIndex =
+            action.source !== undefined
+              ? routes.findIndex((route) => route.key === action.source)
+              : state.index;
+
+          if (
+            currentIndex === -1 ||
+            routes.length === 1 ||
+            action.payload.count < 1
+          ) {
+            return null;
+          }
+
+          const count = Math.min(
+            action.payload.count,
+            currentIndex + 1,
+            routes.length - 1
+          );
+
+          const firstIndex = currentIndex - count + 1;
+
+          return retainRoutes(
+            state,
+            getStateWithRoutes(
+              state,
+              routes.slice(0, firstIndex).concat(routes.slice(currentIndex + 1))
+            )
+          );
+        }
+
         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) {
@@ -568,30 +810,26 @@ export function StackRouter(options: StackRouterOptions) {
               };
             }
 
-            return {
-              ...state,
-              index: 0,
-              routes: [route],
-            };
+            return retainRoutes(state, getStateWithRoutes(state, [route]));
           }
 
           return null;
         }
 
         case 'POP_TO': {
+          if (!state.routeNames.includes(action.payload.name)) {
+            return null;
+          }
+
           const currentIndex =
-            action.target === state.key && action.source
-              ? state.routes.findLastIndex((r) => r.key === action.source)
+            action.source !== undefined
+              ? routes.findIndex((r) => r.key === action.source)
               : state.index;
 
           if (currentIndex === -1) {
             return null;
           }
 
-          if (!state.routeNames.includes(action.payload.name)) {
-            return null;
-          }
-
           // If the route already exists, navigate to it
           let index = -1;
           let historyIndex: number | undefined;
@@ -601,7 +839,11 @@ export function StackRouter(options: StackRouterOptions) {
 
           if (id !== undefined) {
             for (let i = currentIndex; i >= 0; i--) {
-              const r = state.routes[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;
@@ -614,9 +856,17 @@ export function StackRouter(options: StackRouterOptions) {
 
               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 (
-                    r.history[j].type === 'params' &&
-                    id === getId?.({ params: r.history[j].params })
+                    historyEntry.type === 'params' &&
+                    id === getId?.({ params: historyEntry.params })
                   ) {
                     index = i;
                     historyIndex = j;
@@ -629,11 +879,29 @@ export function StackRouter(options: StackRouterOptions) {
                 }
               }
             }
-          } else if (state.routes[currentIndex].name === action.payload.name) {
-            index = currentIndex;
           } 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;
               }
@@ -642,8 +910,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 })
@@ -651,27 +919,45 @@ 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 = state.routes[index];
+          const route = routes[index];
+
+          if (route == null) {
+            throw new Error(`Couldn't find a route at index ${index}.`);
+          }
 
           let baseParams = route.params;
           let history = route.history;
 
           if (historyIndex !== undefined && route.history) {
-            baseParams = route.history[historyIndex].params;
+            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);
           }
 
@@ -691,73 +977,104 @@ export function StackRouter(options: StackRouterOptions) {
             params = createParamsFromAction({ action, routeParamList });
           }
 
-          return {
-            ...state,
-            index,
-            routes: [
-              ...state.routes.slice(0, index),
+          return retainRoutes(
+            state,
+            getStateWithRoutes(state, [
+              ...routes.slice(0, index),
               params !== baseParams || historyIndex !== undefined
                 ? { ...route, params, history }
-                : state.routes[index],
-            ],
-          };
+                : route,
+            ])
+          );
         }
 
-        case 'GO_BACK':
-          if (state.index > 0 || state.routes[state.index].history?.length) {
-            return router.getStateForAction(
-              state,
-              {
-                type: 'POP',
-                payload: { count: 1 },
-                target: action.target,
-                source: action.source,
-              },
-              options
-            );
-          }
+        case 'GO_BACK': {
+          return router.getStateForAction(
+            state,
+            {
+              type: 'POP',
+              payload: { count: 1 },
+              target: action.target,
+              source: action.source,
+            },
+            options
+          );
+        }
 
-          return null;
+        case 'RETAIN': {
+          const route = routes[state.index];
 
-        case 'PRELOAD': {
-          const getId = options.routeGetIdList[action.payload.name];
-          const id = getId?.({ params: action.payload.params });
+          if (route == null) {
+            throw new Error(`Couldn't find a route at index ${state.index}.`);
+          }
 
-          let route: Route<string> | undefined;
+          const routeKey = action.source ?? route.key;
 
-          if (id !== undefined) {
-            route = state.routes.find(
-              (route) =>
-                route.name === action.payload.name &&
-                id === getId?.({ params: route.params })
-            );
+          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 === 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:
@@ -765,10 +1082,6 @@ export function StackRouter(options: StackRouterOptions) {
       }
     },
 
-    getRoutesFromState(state) {
-      return [...state.routes, ...state.preloadedRoutes];
-    },
-
     actionCreators: StackActions,
   };