Merge pull request #10 from Eliav2:dev

0.3.0

Author: Eliav2

Diff for: README.md

@@ -50,34 +50,34 @@ use `TypedRouter` from `express-typed` instead of `express.Router`, the rest of
 
 ```typescript
 import express from "express";
-import {TypedRouter, ParseRoutes} from "express-typed";
+import { TypedRouter, ParseRoutes } from "express-typed";
 
 const app = express();
 
 //// THIS:
 const router = express.Router();
 
 router.get("/", async (req: Request, res: Response) => {
-    res.send("Hello World!").status(200);
+  res.send("Hello World!").status(200);
 });
 router.post("/", async (req, res) => {
-    res.send(req.body).status(200);
+  res.send(req.body).status(200);
 });
 
 app.use(router);
 //// -->
 //// BECOMES THIS:
 const typedRouter = new TypedRouter({
-    get: {
-        "/": async (req, res) => {
-            res.send("Hello World!").status(200);
-        },
+  get: {
+    "/": async (req, res) => {
+      res.send("Hello World!").status(200);
     },
-    post: {
-        "/": async (req, res) => {
-            res.send(req.body).status(200);
-        },
+  },
+  post: {
+    "/": async (req, res) => {
+      res.send(req.body).status(200);
     },
+  },
 });
 
 app.use(typedRouter.router);
@@ -87,7 +87,7 @@ export type AppRoutes = ParseRoutes<typeof typedRouter>;
 /////
 
 app.listen(3000, () => {
-    console.log("Server is running on port 3000");
+  console.log("Server is running on port 3000");
 });
 ```
 
@@ -150,12 +150,12 @@ utilizing helper types from `express-typed`.
 `RouteResResolver` is used to extract the response type from a specific route.
 
 ```ts
-import {GetRouteResponseInfo, GetRouteResponseInfoHelper} from "express-typed";
+import { GetRouteResponseInfo, GetRouteResponseInfoHelper } from "express-typed";
 //// RouteResResolver
 export type RouteResResolver<
-    Path extends keyof AppRoutes,
-    Method extends keyof AppRoutes[Path],
-    Info extends keyof GetRouteResponseInfoHelper<AppRoutes, Path, Method> | "body" = "body"
+  Path extends keyof AppRoutes,
+  Method extends keyof AppRoutes[Path],
+  Info extends keyof GetRouteResponseInfoHelper<AppRoutes, Path, Method> | "body" = "body"
 > = GetRouteResponseInfo<AppRoutes, Path, Method, Info>;
 ```
 
@@ -183,38 +183,38 @@ and `react-query`(from [here](/examples/fullstack_react_express-typed/frontend-d
 
 ```ts
 // queries.ts
-import {useQuery} from "@tanstack/react-query";
-import axios, {type AxiosStatic} from "axios";
-import type {AppRoutes, RouteResResolver} from "your-backend-package/src/routes/index.routes";
+import { useQuery } from "@tanstack/react-query";
+import axios, { type AxiosStatic } from "axios";
+import type { AppRoutes, RouteResResolver } from "your-backend-package/src/routes/index.routes";
 
 // an hook to fetch response from server, for any possible method(GET, POST, PUT, DELETE)
 export const useAppQuery = <Path extends keyof AppRoutes, Method extends Extract<keyof AxiosStatic, keyof AppRoutes[Path]>>(
-    path: Path,
-    method: Method
+  path: Path,
+  method: Method
 ) => {
-    return useQuery<RouteResResolver<Path, Method>>({
-        queryKey: [path],
-        queryFn: async () => {
-            const res = await (axios as any)[method](`/api${path}`);
-            return res.data as RouteResResolver<Path, Method>;
-        },
-    });
+  return useQuery<RouteResResolver<Path, Method>>({
+    queryKey: [path],
+    queryFn: async () => {
+      const res = await (axios as any)[method](`/api${path}`);
+      return res.data as RouteResResolver<Path, Method>;
+    },
+  });
 };
 ```
 
 and usage(see [here](/examples/fullstack_react_express-typed/frontend-demo/src/App.tsx)):
 
 ```tsx
-import {useAppQuery} from "./queries";
+import { useAppQuery } from "./queries";
 
 function App() {
-    const query = useAppQuery("/", "get");
-    const data = query.data;
-    //    ^? const query: UseQueryResult<"Hello world", Error>
+  const query = useAppQuery("/", "get");
+  const data = query.data;
+  //    ^? const query: UseQueryResult<"Hello world", Error>
 
-    console.log("data", data);
+  console.log("data", data);
 
-    return <>{JSON.stringify(data)}</>;
+  return <>{JSON.stringify(data)}</>;
 }
 
 export default App;
@@ -233,22 +233,22 @@ export default App;
 `RouteReqResolver` is defined on your side with the help of `GetRouteRequestHelper` and `GetRouteRequest`:
 
 ```ts
-import {GetRouteRequestHelper, GetRouteRequest, TypedRouter} from "express-typed";
+import { GetRouteRequestHelper, GetRouteRequest, TypedRouter } from "express-typed";
 
 export type RouteReqResolver<
-    Path extends keyof AppRoutes,
-    Method extends keyof AppRoutes[Path],
-    Info extends keyof GetRouteRequestHelper<AppRoutes, Path, Method> = Extract<keyof GetRouteRequestHelper<AppRoutes, Path, Method>, "body">
+  Path extends keyof AppRoutes,
+  Method extends keyof AppRoutes[Path],
+  Info extends keyof GetRouteRequestHelper<AppRoutes, Path, Method> = Extract<keyof GetRouteRequestHelper<AppRoutes, Path, Method>, "body">
 > = GetRouteRequest<AppRoutes, Path, Method, Info>;
 
 const typedRouter = new TypedRouter({
-    "/": {
-        get: (req: TypedRequest<{ body: "bb"; query: "qq" }>, res) => {
-            const body = req.body;
-            const test = res.send("Home").status(200);
-            return test;
-        },
+  "/": {
+    get: (req: TypedRequest<{ body: "bb"; query: "qq" }>, res) => {
+      const body = req.body;
+      const test = res.send("Home").status(200);
+      return test;
     },
+  },
 });
 
 type HomePageBody = RouteReqResolver<"/", "get">;
@@ -261,24 +261,24 @@ example of using this info with react-query mutation(
 see [here](/examples/fullstack_react_express-typed/frontend-demo/src/mutations.ts)):
 
 ```ts
-import {DefaultError, useMutation} from "@tanstack/react-query";
+import { DefaultError, useMutation } from "@tanstack/react-query";
 import axios from "axios";
-import {AppRoutes, RouteReqResolver, RouteResResolver} from "express-typed-demo/src/routes/index.routes";
+import { AppRoutes, RouteReqResolver, RouteResResolver } from "express-typed-demo/src/routes/index.routes";
 
 const useAppMutation = <Path extends keyof AppRoutes, Method extends keyof AppRoutes[Path]>(path: Path, method: Method) => {
-    const mutation = useMutation<RouteResResolver<Path, Method>, DefaultError, RouteReqResolver<Path, Method>>({
-        mutationKey: ["mutation", path, method],
-        mutationFn: async () => {
-            const res = await (axios as any)[method](`/api${path}`);
-            return res.data as RouteResResolver<Path, Method>;
-        },
-    });
-    return mutation;
+  const mutation = useMutation<RouteResResolver<Path, Method>, DefaultError, RouteReqResolver<Path, Method>>({
+    mutationKey: ["mutation", path, method],
+    mutationFn: async () => {
+      const res = await (axios as any)[method](`/api${path}`);
+      return res.data as RouteResResolver<Path, Method>;
+    },
+  });
+  return mutation;
 };
 
 // completly type safe
 const testMutation = useAppMutation("/mutate", "post");
-testMutation.mutate({name: "test"});
+testMutation.mutate({ name: "test" });
 ```
 
 </details>
@@ -294,7 +294,7 @@ testMutation.mutate({name: "test"});
 `RoutesWithMethod` is used to extract all the routes with a specific method from the routes object.
 
 ```ts
-import {GetRoutesWithMethod, GetRouterMethods} from "express-typed";
+import { GetRoutesWithMethod, GetRouterMethods } from "express-typed";
 //// RoutesWithMethod
 export type RoutesWithMethod<Method extends GetRouterMethods<AppRoutes>> = GetRoutesWithMethod<AppRoutes, Method>;
 ```
@@ -314,32 +314,32 @@ type PostRoutes = RoutesWithMethod<"post">;
 then in your frontend codebase, you can define the following react-query hooks:
 
 ```ts
-import {useQuery} from "@tanstack/react-query";
+import { useQuery } from "@tanstack/react-query";
 import axios from "axios";
-import type {RoutesWithMethod} from "express-typed-demo/src/routes/index.routes";
+import type { RoutesWithMethod } from "express-typed-demo/src/routes/index.routes";
 
 // an hook to fetch response from server, for GET method
 type GetRoutes = RoutesWithMethod<"get">;
 export const useAppGetQuery = <P extends keyof GetRoutes>(path: P) => {
-    return useQuery<GetRoutes[P]>({
-        queryKey: [path],
-        queryFn: async () => {
-            const res = await axios.get(`/api${path}`);
-            return res.data as GetRoutes[P];
-        },
-    });
+  return useQuery<GetRoutes[P]>({
+    queryKey: [path],
+    queryFn: async () => {
+      const res = await axios.get(`/api${path}`);
+      return res.data as GetRoutes[P];
+    },
+  });
 };
 
 // an hook to fetch response from server, for POST method
 type PostRoutes = RoutesWithMethod<"post">;
 export const useAppPostQuery = <P extends keyof PostRoutes>(path: P) => {
-    return useQuery<PostRoutes[P]>({
-        queryKey: [path],
-        queryFn: async () => {
-            const res = await axios.post(`/api${path}`);
-            return res.data as PostRoutes[P];
-        },
-    });
+  return useQuery<PostRoutes[P]>({
+    queryKey: [path],
+    queryFn: async () => {
+      const res = await axios.post(`/api${path}`);
+      return res.data as PostRoutes[P];
+    },
+  });
 };
 ```
 
@@ -357,19 +357,19 @@ see full example [here](/examples/fullstack_react_express-typed/express-typed-de
 
 ```typescript
 import {
-    GetRouteRequest,
-    GetRouteRequestHelper,
-    GetRouteResponseInfo,
-    GetRouteResponseInfoHelper,
-    GetRouterMethods,
-    GetRoutesWithMethod,
-    ParseRoutes,
-    TypedRequest,
-    TypedRouter,
+  GetRouteRequest,
+  GetRouteRequestHelper,
+  GetRouteResponseInfo,
+  GetRouteResponseInfoHelper,
+  GetRouterMethods,
+  GetRoutesWithMethod,
+  ParseRoutes,
+  TypedRequest,
+  TypedRouter,
 } from "express-typed";
 
 const typedRouter = new TypedRouter({
-    // your routes here     
+  // your routes here
 });
 
 export default typedRouter;
@@ -381,23 +381,88 @@ export default typedRouter;
 export type AppRoutes = ParseRoutes<typeof typedRouter>;
 
 export type RouteResResolver<
-    // example usage
-    Path extends keyof AppRoutes,
-    Method extends keyof AppRoutes[Path],
-    Info extends keyof GetRouteResponseInfoHelper<AppRoutes, Path, Method> | "body" = "body"
+  // example usage
+  Path extends keyof AppRoutes,
+  Method extends keyof AppRoutes[Path],
+  Info extends keyof GetRouteResponseInfoHelper<AppRoutes, Path, Method> | "body" = "body"
 > = GetRouteResponseInfo<AppRoutes, Path, Method, Info>;
 
 export type RouteReqResolver<
-    Path extends keyof AppRoutes,
-    Method extends keyof AppRoutes[Path],
-    Info extends keyof GetRouteRequestHelper<AppRoutes, Path, Method> = Extract<keyof GetRouteRequestHelper<AppRoutes, Path, Method>, "body">
+  Path extends keyof AppRoutes,
+  Method extends keyof AppRoutes[Path],
+  Info extends keyof GetRouteRequestHelper<AppRoutes, Path, Method> = Extract<keyof GetRouteRequestHelper<AppRoutes, Path, Method>, "body">
 > = GetRouteRequest<AppRoutes, Path, Method, Info>;
 
 export type RoutesWithMethod<Method extends GetRouterMethods<AppRoutes>> = GetRoutesWithMethod<AppRoutes, Method>;
 ```
 
 </details>
 
+## Quick walkthrough
+
+This demo highlights the key usage and features of express-typed, including type inference, explicit typing, and nested routes. follow the comments line by line to understand the usage better.
+
+```ts
+import { TypedRequest, TypedResponse, TypedRouter, ParseRoutes } from "express-typed";
+
+const typedRouter = new TypedRouter({
+  // returned type is inferred
+  "/": {
+    get: (req, res) => {
+      return res.send("get: /").status(200);
+    },
+    post: (req, res) => {
+      return res.send("post: /").status(200);
+    },
+  },
+  // request body is explicitly typed, response is inferred based on the return value
+  "/explicit-req": {
+    get: (req: TypedRequest<{ body: { name: string } }>, res) => {
+      const body = req.body;
+      //    ^?
+      return res.json(req.body).status(200);
+    },
+  },
+  // response body is explicitly typed, retrun type must at least extend { name: string }
+  "/explicit-res": {
+    get: (req, res: TypedResponse<{ body: { name: string } }>) => {
+      return res.json({ name: "eliav" }).status(200);
+    },
+  },
+  // nested router are allowed, and fully typed
+  "/nested": new TypedRouter({
+    "/": {
+      get: (req, res) => {
+        const test = res.send("get /nested/").status(200);
+        return test;
+      },
+      // async methods are supported
+      post: async (req, res) => {
+        const test = (await (await fetch("https://jsonplaceholder.typicode.com/todos/1")).json()) as {
+          userId: number;
+          id: number;
+          title: string;
+          completed: boolean;
+        };
+        return res.json(test).status(200);
+      },
+    },
+    // any of "all" | "get" | "post" | "put" | "delete" | "patch" | "options" | "head" is allowed as a method
+    "/all": {
+      all: (req, res) => {
+        return res.send("responding to all methods");
+      },
+    },
+  }),
+});
+
+export default typedRouter;
+
+export type AppRoutes = ParseRoutes<typeof typedRouter>;
+```
+
+and pretty much, that's it! you can now use the types defined in `AppRoutes` to ensure type safety in your frontend codebase.
+
 ## Contributing
 
 This library is still in its early stages, and that's exactly the time to suggest significant changes.
@@ -416,5 +481,6 @@ like Fastify, Koa, etc.
 - [x] nested routers support
 - [x] backend return type inference(the type that the backend returns)
 - [x] backend request type inference(the type that the backend expects in the request)
+- [x] explicitly typed request/response
 - [ ] type-safe path parameters
 - [ ] type-safe query parameters