React router

README.md

@@ -1,7 +1,115 @@
 # React Typescript Starter
 
 ## Dependencies
-* Enzyme
+* [enzyme](https://airbnb.io/enzyme/)
+* [react-router](https://github.com/ReactTraining/react-router)
 
-### Enzyme
+## Enzyme
 [Enzyme](https://airbnb.io/enzyme/) was set up with [Using Jest with TypeScript](https://basarat.gitbooks.io/typescript/docs/testing/jest.html) (describes how to setup both jest and enzyme).
+
+## Routing
+
+### Create a scene
+**Note:** To simplify things I will use the already created `UserEdit` scene for the following instructions.
+
+How to type-safe create and register a new scene in 6 easy steps:
+1. Create a new `UserEdit.scene.tsx` file in `modules/user/scenes`
+2. Define a interface for the scene params if there are any and export it. It is important that you extend from the interface `SceneParams`. Here is the actual code:
+```
+export interface UserEditSceneParams extends SceneParams {
+   userId: string;
+   projId: string;
+}
+```
+3. Now define and export `paramsSchema` with the type `UserEditSceneParams`:
+```
+const paramsSchema: UserEditSceneParams = {
+  projId: '',
+  userId: '',
+};
+```
+Honestly this only exist to avoid defining the path of a route with params like: `'/user/edit/:projId/:userId/'`. The final path will be auto-generated with the Route enum and the params schema using the helper funtion [`getRoutePath`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/shared/helper/routing/routing.helper.ts#L7) that get called in the [`mapRoutes`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/App.router.tsx#L11) function. With this approach you get errors at compile time when you forget to change the params at one place thanks to TypeScript.
+
+4. Define the actual component (what should be rendered when navigating to this scene). To get TypeScript autocomplete support for your scene params don't forget to create your component like:
+```
+export const UserEditScene: React.SFC<
+   RouteComponentProps<UserEditSceneParams>> = props => {
+      const { userId, projId } = props.match.params;
+      return (
+         ...
+      );
+   };
+```
+
+5. At the bottom you have to create a `UserEditScene` interface with the correct scene params and then an `AppRoute` object called `userEditRoute`. Both have to be exported. It should look like this:
+```
+export interface UserEditScene extends IScene<UserRoute.Edit> {
+  params: UserEditSceneParams;
+}
+
+export const userEditRoute: AppRoute = {
+  scene: {
+    path: UserRoute.Edit,
+    params: paramsSchema,
+  },
+  component: UserEditScene,
+};
+```
+**Important:** The `UserRoute.Edit` will not exist at this time. You will define it in step 6.
+
+**Hint:** The parameter of `IScene` is the path of the scene (Route enum).
+
+**Important:** If a scene doesn't have any params like the [`UserListScene`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/modules/user/scenes/UserList.scene.tsx) you have to define the interface like this:
+   ```
+     export interface UserListScene extends IScene<UserRoute.List> {
+     params?: never;
+   }
+   ```
+Also you don't need to create a `paramsSchema` object.
+
+Here is the correctly created [file](https://github.com/npeham/react-typescript-starter/blob/react-router/src/modules/user/scenes/UserEdit.scene.tsx).
+
+
+6. Open the file [`modules/user/user.routing.ts`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/modules/user/user.routes.ts) - you have to add/change 3 things here.
+   * At first create a new entry in the `UserRoute` enum:
+   ```
+   export enum UserRoute {
+      ...
+      Edit = '/user/edit',
+      ...
+   }
+   ```
+   * Add the `userEditRoute` to the `AppRoute` array `userRoutes`:
+   ```
+      export const userRoutes: AppRoute[] = [userEditRoute, userListScene];
+   ```
+   * At least add the `UserEditScene` to the `UserScenes` type:
+   ```
+      export type UserScenes = UserEditScene | UserListScene;
+   ```
+ **Notice:** The enum doesn't include the params like `'/user/edit/:projId/:userId/'` thanks to the `paramsSchema` object and the [`getRoutePath`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/shared/helper/routing/routing.helper.ts#L7) function.
+
+
+7. (optional) If you are creating the first scene in your module you also have to do:
+- Add the `UserScenes` to the exported `Scenes` type in the [`types/routing.ts`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/shared/types/routing.ts) file.
+- Add `mapRoutes(userRoutes)` to the `Switch` tag in the [`App.router.ts`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/App.router.tsx) file.
+
+
+### Navigate to a scene
+If you want to navigate to a scene you have to call the [`getPathWithParams`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/shared/helper/routing/routing.helper.ts#L19) function:
+```
+const userEditScenePath = getPathWithParams({
+  path: UserRoute.Edit,
+  params: {
+    projId: '3',
+    userId: '8',
+  },
+});
+```
+The result is a valid path where you can route to with `react-router`:
+```
+<button onClick={() => props.history.push(userEditScenePath)}>
+   click
+</button>
+```
+**Notice:** Thank to our type-safe setup TypeScript will know the params of the scene based on the path (Route enum) you passed to [`getPathWithParams`](https://github.com/npeham/react-typescript-starter/blob/react-router/src/shared/helper/routing/routing.helper.ts#L19) function. So you will get nice autocompletion and you cannot pass the wrong params.

index.html

@@ -4,6 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta http-equiv="X-UA-Compatible" content="ie=edge" />
+    <base href="/" />
     <link
       rel="stylesheet"
       href="https://fonts.googleapis.com/css?family=Roboto:300,400,500"

package.json

@@ -13,6 +13,7 @@
   "dependencies": {
     "react": "^16.4.2",
     "react-dom": "^16.4.2",
+    "react-router": "^4.3.1",
     "react-router-dom": "^4.3.1"
   },
   "devDependencies": {
@@ -21,6 +22,8 @@
     "@types/jest": "^24.0.9",
     "@types/react": "^16.4.11",
     "@types/react-dom": "^16.0.7",
+    "@types/react-router": "^4.4.4",
+    "@types/react-router-dom": "^4.3.1",
     "enzyme": "^3.9.0",
     "enzyme-adapter-react-16": "^1.10.0",
     "enzyme-to-json": "^3.3.5",

src/App.router.tsx

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import { Switch, Route } from 'react-router';
+import { AppRoute } from './shared/types/routing';
+import { PrivateRoute } from './shared/components/PrivateRoute';
+import { userRoutes } from './modules/user/user.routing';
+import { postRoutes } from './modules/post/post.routing';
+import { verifyIfPathOfSceneIsUnique } from './shared/helper/routing/routing.helper';
+
+const existingPaths: string[] = [];
+
+const mapRoutes = (routeProps: AppRoute[]) => {
+  return routeProps.map(({ isPrivate, scene, ...rest }) => {
+    const path = verifyIfPathOfSceneIsUnique(scene, existingPaths);
+    existingPaths.push(path);
+    const key = path;
+
+    return isPrivate ? (
+      <PrivateRoute {...{ ...rest, key, path }} />
+    ) : (
+      <Route {...{ ...rest, key, path }} />
+    );
+  });
+};
+
+export const AppRouter = () => (
+  <Switch>
+    {mapRoutes(userRoutes)}
+    {mapRoutes(postRoutes)}
+  </Switch>
+);

src/App.tsx

@@ -1,3 +1,4 @@
 import * as React from 'react';
+import { AppRouter } from './App.router';
 
-export const App = () => <div>working</div>;
+export const App = () => <AppRouter />;

src/index.tsx

@@ -1,10 +1,16 @@
 import * as React from 'react';
 import * as ReactDOM from 'react-dom';
+import { BrowserRouter } from 'react-router-dom';
+
 declare let module: any;
 
 import { App } from './App';
 
-const RenderApp = () => <App />;
+const RenderApp = () => (
+  <BrowserRouter>
+    <App />
+  </BrowserRouter>
+);
 
 ReactDOM.render(<RenderApp />, document.getElementById('root') as HTMLElement);
 

src/modules/post/post.routing.ts

@@ -0,0 +1,10 @@
+import { AppRoute } from '../../shared/types/routing';
+import { PostDetailScene, postDetailRoute } from './scenes/PostDetail.scene';
+
+export const enum PostRoute {
+  Detail = '/post',
+}
+
+export const postRoutes: AppRoute[] = [postDetailRoute];
+
+export type PostScenes = PostDetailScene;

src/modules/post/scenes/PostDetail.scene.tsx

@@ -0,0 +1,46 @@
+import * as React from 'react';
+import { RouteComponentProps } from 'react-router';
+import { SceneParams, AppRoute, IScene } from '../../../shared/types/routing';
+import { UserRoute } from '../../user/user.routing';
+import { PostRoute } from '../post.routing';
+import { getPathWithParams } from '../../../shared/helper/routing/routing.helper';
+
+export interface PostDetailSceneParams extends SceneParams {
+  postId: string;
+}
+
+const paramsSchema: PostDetailSceneParams = {
+  postId: '',
+};
+
+export const PostDetailScene = (
+  props: RouteComponentProps<PostDetailSceneParams>,
+) => {
+  const userEditScenePath = getPathWithParams({
+    path: UserRoute.Edit,
+    params: {
+      projId: '3',
+      userId: '9',
+    },
+  });
+  return (
+    <React.Fragment>
+      <div>post detail --> postId: {props.match.params.postId}</div>
+      <button onClick={() => props.history.push(userEditScenePath)}>
+        click
+      </button>
+    </React.Fragment>
+  );
+};
+
+export interface PostDetailScene extends IScene<PostRoute.Detail> {
+  params: PostDetailSceneParams;
+}
+
+export const postDetailRoute: AppRoute = {
+  component: PostDetailScene,
+  scene: {
+    path: PostRoute.Detail,
+    params: paramsSchema,
+  },
+};

src/modules/user/scenes/UserEdit.scene.tsx

@@ -0,0 +1,39 @@
+import * as React from 'react';
+import { RouteComponentProps } from 'react-router';
+import { SceneParams, AppRoute, IScene } from '../../../shared/types/routing';
+import { UserRoute } from '../user.routing';
+
+export interface UserEditSceneParams extends SceneParams {
+  userId: string;
+  projId: string;
+}
+
+const paramsSchema: UserEditSceneParams = {
+  projId: '',
+  userId: '',
+};
+
+export const UserEditScene: React.SFC<
+  RouteComponentProps<UserEditSceneParams>
+> = props => {
+  const { userId, projId } = props.match.params;
+  return (
+    <div>
+      <span>userId --> {userId}</span>
+      <br />
+      <span>projId --> {projId}</span>
+    </div>
+  );
+};
+
+export interface UserEditScene extends IScene<UserRoute.Edit> {
+  params: UserEditSceneParams;
+}
+
+export const userEditRoute: AppRoute = {
+  scene: {
+    path: UserRoute.Edit,
+    params: paramsSchema,
+  },
+  component: UserEditScene,
+};

src/modules/user/scenes/UserList.scene.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { IScene, AppRoute } from '../../../shared/types/routing';
+import { UserRoute } from '../user.routing';
+import { RouteComponentProps } from 'react-router';
+
+export const UserListScene: React.SFC<RouteComponentProps> = props => {
+  return <div>user list</div>;
+};
+
+export interface UserListScene extends IScene<UserRoute.List> {
+  params?: never;
+}
+
+export const userListScene: AppRoute = {
+  scene: {
+    path: UserRoute.List,
+  },
+  component: UserListScene,
+};

src/modules/user/user.routing.ts

@@ -0,0 +1,12 @@
+import { userEditRoute, UserEditScene } from './scenes/UserEdit.scene';
+import { UserListScene, userListScene } from './scenes/UserList.scene';
+import { AppRoute } from '../../shared/types/routing';
+
+export const enum UserRoute {
+  List = '/user/list',
+  Edit = '/user/edit',
+}
+
+export const userRoutes: AppRoute[] = [userEditRoute, userListScene];
+
+export type UserScenes = UserEditScene | UserListScene;

src/shared/components/PrivateRoute.tsx

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { RouteProps, Route } from 'react-router';
+
+type PrivateRoute = RouteProps;
+
+export const PrivateRoute: React.SFC<PrivateRoute> = props => (
+  <Route {...props} />
+);

src/shared/helper/object/object.helper.test.ts

@@ -0,0 +1,42 @@
+import { overrideUndefinedValues } from './object.helper';
+
+type TestObject = {
+  firstValue: string;
+  secondValue: number;
+};
+
+describe('object helper tests', () => {
+  describe('overrideUndefinedValues', () => {
+    const defaultObject: TestObject = {
+      firstValue: 'default',
+      secondValue: 0,
+    };
+
+    it('returns merged params', () => {
+      const testObjectWithUndefinedValue: TestObject = {
+        firstValue: '5',
+        // @ts-ignore
+        secondValue: undefined,
+      };
+      const mergedParams: TestObject = {
+        ...testObjectWithUndefinedValue,
+        secondValue: defaultObject.secondValue,
+      };
+
+      expect(
+        overrideUndefinedValues(testObjectWithUndefinedValue, defaultObject),
+      ).toEqual(mergedParams);
+    });
+
+    it('returns the correct params when no one is undefined', () => {
+      const testObject: TestObject = {
+        firstValue: '5',
+        secondValue: 0,
+      };
+
+      expect(overrideUndefinedValues(testObject, defaultObject)).toEqual(
+        testObject,
+      );
+    });
+  });
+});

src/shared/helper/object/object.helper.ts

@@ -0,0 +1,18 @@
+type StringSignature = { [key: string]: any };
+
+export function overrideUndefinedValues<T extends StringSignature>(
+  params: T,
+  overrideWith: T,
+): T {
+  const paramKeys = Object.keys(params);
+
+  const undefinedParamKeys = paramKeys.filter(
+    (paramKey: string) => params[paramKey] === undefined,
+  );
+
+  const mergedParams = undefinedParamKeys.reduce((prev, undefinedParamKey) => {
+    return { ...prev, [undefinedParamKey]: overrideWith[undefinedParamKey] };
+  },                                             params);
+
+  return mergedParams;
+}