feat: make NAVIGATE and JUMP_TO to support key and name of the route

example/StackNavigator.tsx

@@ -151,25 +151,42 @@ const StackRouter: Router<CommonAction | Action> = {
         });
 
       case 'NAVIGATE':
-        if (state.routeNames.includes(action.payload.name)) {
+        if (
+          action.payload.key ||
+          (action.payload.name &&
+            state.routeNames.includes(action.payload.name))
+        ) {
           // If the route already exists, navigate to that
           let index = -1;
 
-          if (state.routes[state.index].name === action.payload.name) {
+          if (
+            state.routes[state.index].name === action.payload.name ||
+            state.routes[state.index].key === action.payload.key
+          ) {
             index = state.index;
           } else {
             for (let i = state.routes.length - 1; i >= 0; i--) {
-              if (state.routes[i].name === action.payload.name) {
+              if (
+                state.routes[i].name === action.payload.name ||
+                state.routes[i].key === action.payload.key
+              ) {
                 index = i;
                 break;
               }
             }
           }
 
-          if (index === -1) {
+          if (index === -1 && action.payload.key) {
+            return null;
+          }
+
+          if (index === -1 && action.payload.name !== undefined) {
             return StackRouter.getStateForAction(state, {
               type: 'PUSH',
-              payload: action.payload,
+              payload: {
+                name: action.payload.name,
+                params: action.payload.params,
+              },
             });
           }
 

example/TabNavigator.tsx

@@ -9,6 +9,7 @@ import {
   ParamListBase,
   Router,
   createNavigator,
+  TargetRoute,
 } from '../src/index';
 
 type Props = {
@@ -18,7 +19,7 @@ type Props = {
 
 type Action = {
   type: 'JUMP_TO';
-  payload: { name: string; params?: object };
+  payload: { name?: string; key?: string; params?: object };
 };
 
 export type TabNavigationProp<
@@ -31,10 +32,10 @@ export type TabNavigationProp<
    * @param name Name of the route for the tab.
    * @param [params] Params object for the route.
    */
-  jumpTo<RouteName extends keyof ParamList>(
+  jumpTo<RouteName extends Extract<keyof ParamList, string>>(
     ...args: ParamList[RouteName] extends void
-      ? [RouteName]
-      : [RouteName, ParamList[RouteName]]
+      ? [TargetRoute<RouteName>]
+      : [TargetRoute<RouteName>, ParamList[RouteName]]
   ): void;
 };
 
@@ -98,35 +99,44 @@ const TabRouter: Router<Action | CommonAction> = {
   },
 
   getStateForAction(state, action) {
+    let index = -1;
     switch (action.type) {
       case 'JUMP_TO':
       case 'NAVIGATE':
-        if (state.routeNames.includes(action.payload.name)) {
-          const index = state.routes.findIndex(
+        if (action.payload.key) {
+          index = state.routes.findIndex(
+            route => route.key === action.payload.key
+          );
+        }
+
+        if (action.payload.name) {
+          index = state.routes.findIndex(
             route => route.name === action.payload.name
           );
+        }
 
-          return {
-            ...state,
-            routes:
-              action.payload.params !== undefined
-                ? state.routes.map((route, i) =>
-                    i === index
-                      ? {
-                          ...route,
-                          params: {
-                            ...route.params,
-                            ...action.payload.params,
-                          },
-                        }
-                      : route
-                  )
-                : state.routes,
-            index,
-          };
+        if (index == -1) {
+          return null;
         }
 
-        return null;
+        return {
+          ...state,
+          routes:
+            action.payload.params !== undefined
+              ? state.routes.map((route, i) =>
+                  i === index
+                    ? {
+                        ...route,
+                        params: {
+                          ...route.params,
+                          ...action.payload.params,
+                        },
+                      }
+                    : route
+                )
+              : state.routes,
+          index,
+        };
 
       case 'REPLACE': {
         return {
@@ -171,8 +181,20 @@ const TabRouter: Router<Action | CommonAction> = {
   },
 
   actionCreators: {
-    jumpTo(name: string, params?: object) {
-      return { type: 'JUMP_TO', payload: { name, params } };
+    jumpTo(target: TargetRoute<string>, params?: object) {
+      if (typeof target === 'string') {
+        return { type: 'JUMP_TO', payload: { name: target, params } };
+      } else {
+        if (
+          (target.hasOwnProperty('key') && target.hasOwnProperty('name')) ||
+          (!target.hasOwnProperty('key') && !target.hasOwnProperty('name'))
+        ) {
+          throw new Error(
+            'While calling jumpTo you need to specify either name or key'
+          );
+        }
+        return { type: 'JUMP_TO', payload: { ...target, params } };
+      }
     },
   },
 };

src/BaseActions.tsx

@@ -1,10 +1,10 @@
-import { PartialState } from './types';
+import { PartialState, TargetRoute } from './types';
 
 export type Action =
   | { type: 'GO_BACK' }
   | {
       type: 'NAVIGATE';
-      payload: { name: string; params?: object };
+      payload: { name?: string; key?: string; params?: object };
     }
   | {
       type: 'REPLACE';
@@ -19,8 +19,20 @@ export function goBack(): Action {
   return { type: 'GO_BACK' };
 }
 
-export function navigate(name: string, params?: object): Action {
-  return { type: 'NAVIGATE', payload: { name, params } };
+export function navigate(target: TargetRoute<string>, params?: object): Action {
+  if (
+    (target.hasOwnProperty('key') && target.hasOwnProperty('name')) ||
+    (!target.hasOwnProperty('key') && !target.hasOwnProperty('name'))
+  ) {
+    throw new Error(
+      'While calling navigate you need to specify either name or key'
+    );
+  }
+  if (typeof target === 'string') {
+    return { type: 'NAVIGATE', payload: { name: target, params } };
+  } else {
+    return { type: 'NAVIGATE', payload: { ...target, params } };
+  }
 }
 
 export function replace(name: string, params?: object): Action {

src/__tests__/BaseActions.test.tsx

@@ -0,0 +1,78 @@
+import * as React from 'react';
+import { render } from 'react-native-testing-library';
+import Screen from '../Screen';
+import NavigationContainer from '../NavigationContainer';
+import useNavigationBuilder from '../useNavigationBuilder';
+import MockRouter from './__fixtures__/MockRouter';
+
+beforeEach(() => (MockRouter.key = 0));
+
+it('throws if NAVIGATE dispatched with both key and name', () => {
+  const TestNavigator = (props: any) => {
+    const { state, descriptors } = useNavigationBuilder(MockRouter, props);
+
+    return descriptors[state.routes[state.index].key].render();
+  };
+
+  const FooScreen = (props: any) => {
+    React.useEffect(() => {
+      props.navigation.navigate({ key: '1', name: '2' });
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    return null;
+  };
+
+  const onStateChange = jest.fn();
+
+  const element = (
+    <NavigationContainer onStateChange={onStateChange}>
+      <TestNavigator initialRouteName="foo">
+        <Screen
+          name="foo"
+          component={FooScreen}
+          initialParams={{ count: 10 }}
+        />
+      </TestNavigator>
+    </NavigationContainer>
+  );
+
+  expect(() => render(element).update(element)).toThrowError(
+    'While calling navigate you need to specify either name or key'
+  );
+});
+
+it('throws if NAVIGATE dispatched neither both key nor name', () => {
+  const TestNavigator = (props: any) => {
+    const { state, descriptors } = useNavigationBuilder(MockRouter, props);
+
+    return descriptors[state.routes[state.index].key].render();
+  };
+
+  const FooScreen = (props: any) => {
+    React.useEffect(() => {
+      props.navigation.navigate({});
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    return null;
+  };
+
+  const onStateChange = jest.fn();
+
+  const element = (
+    <NavigationContainer onStateChange={onStateChange}>
+      <TestNavigator initialRouteName="foo">
+        <Screen
+          name="foo"
+          component={FooScreen}
+          initialParams={{ count: 10 }}
+        />
+      </TestNavigator>
+    </NavigationContainer>
+  );
+
+  expect(() => render(element).update(element)).toThrowError(
+    'While calling navigate you need to specify either name or key'
+  );
+});

src/types.tsx

@@ -2,6 +2,11 @@ import * as BaseActions from './BaseActions';
 
 export type CommonAction = BaseActions.Action;
 
+export type TargetRoute<RouteName extends string> =
+  | RouteName
+  | { name: RouteName }
+  | { key: string };
+
 export type NavigationState = {
   /**
    * Unique key for the navigation state.
@@ -163,10 +168,10 @@ export type NavigationHelpers<
    * @param name Name of the route to navigate to.
    * @param [params] Params object for the route.
    */
-  navigate<RouteName extends keyof ParamList>(
+  navigate<RouteName extends Extract<keyof ParamList, string>>(
     ...args: ParamList[RouteName] extends undefined
-      ? [RouteName] | [RouteName, undefined]
-      : [RouteName, ParamList[RouteName]]
+      ? [TargetRoute<RouteName>] | [TargetRoute<RouteName>, undefined]
+      : [TargetRoute<RouteName>, ParamList[RouteName]]
   ): void;
 
   /**