\n\nhttps://user-images.githubusercontent.com/633115/185851987-554f5686-cb78-4096-8ff5-c8d61b645608.mp4\n\n# What is it ?\n\nIt's an express adapter for zodios that helps you type your express routes.\n \n- really simple centralized API declaration\n- router endpoints autocompletion\n- typescript autocompletion for query, path, header and body input parameters (`req` is fully typed)\n- typescript autocompletion for response body (`res.json()`)\n- input validation thanks to zod\n- openapi specification generation out of the box (using swagger)\n- end to end typesafe APIs (a la tRPC when using both @zodios/express and @zodios/core)\n \n**Table of contents:**\n\n- [What is it ?](#what-is-it-)\n- [Install](#install)\n- [How to use it ?](#how-to-use-it-)\n - [`zodiosApp` : Declare your API for fullstack end to end type safety](#zodiosapp--declare-your-api-for-fullstack-end-to-end-type-safety)\n - [`zodiosRouter` : Split your application with multiple routers](#zodiosrouter--split-your-application-with-multiple-routers)\n - [Error Handling](#error-handling)\n- [Roadmap](#roadmap)\n\n# Install\n\n```bash\n> npm install @zodios/express\n```\n\nor\n\n```bash\n> yarn add @zodios/express\n```\n\n# How to use it ?\n\nFor an almost complete example on how to use zodios and how to split your APIs declarations, take a look at [dev.to](examples/dev.to/) example.\n\n## `zodiosApp` : Declare your API for fullstack end to end type safety\n\nHere is an example of API declaration with Zodios.\n \nin a common directory (ex: `src/common/api.ts`) :\n\n```typescript\nimport { makeApi } from \"@zodios/core\";\nimport { z } from \"zod\";\n\nconst userApi = makeApi([\n {\n method: \"get\",\n path: \"/users/:id\", // auto detect :id and ask for it in apiClient get params\n alias: \"getUser\", // optionnal alias to call this endpoint with it\n description: \"Get a user\",\n response: z.object({\n id: z.number(),\n name: z.string(),\n }),\n },\n]);\n```\n\nin your frontend (ex: `src/client/api.ts`) :\n\n```typescript\nimport { Zodios } from \"@zodios/core\";\nimport { userApi } from \"../../common/api\";\n\nconst apiClient = new Zodios(\n \"https://jsonplaceholder.typicode.com\",\n userApi\n);\n\n// typed alias auto-complete params\n// ▼ ▼ ▼\nconst user = await apiClient.getUser({ params: { id: 1 } });\n```\n\nin your backend (ex: `src/server/router.ts`) :\n```typescript\nimport { zodiosApp } from \"@zodios/express\";\nimport { userApi } from \"../../common/api\";\n\n// just an express adapter that is aware of your api, app is just an express app with type annotations and validation middlewares\nconst app = zodiosApp(userApi);\n\n// auto-complete path fully typed and validated input params (body, query, path, header)\n// ▼ ▼ ▼\napp.get(\"/users/:id\", (req, res) => {\n // res.json is typed thanks to zod\n res.json({\n // auto-complete req.params.id\n // ▼\n id: req.params.id,\n name: \"John Doe\",\n });\n})\n\napp.listen(3000);\n```\n\n## `zodiosRouter` : Split your application with multiple routers\n\nWhen organizing your express application, you usually want to split your API declarations into separate Routers.\nYou can use the `zodiosRouter` to do that with a `zodiosApp` without APIs attached.\n\n```typescript\nimport { zodiosApp, zodiosRouter } from \"@zodios/express\";\n\nconst app = zodiosApp(); // just an axpess app with type annotations\nconst userRouter = zodiosRouter(userApi); // just an express router with type annotations and validation middlewares\nconst adminRouter = zodiosRouter(adminApi); // just an express router with type annotations and validation middlewares\n\nconst app.use(userRouter,adminRouter);\n\napp.listen(3000);\n```\n## Error Handling\n\nZodios express can infer the status code to match your API error response and also have your errors correctly typed.\n\n```typescript\nimport { makeApi } from \"@zodios/core\";\nimport { zodiosApp } from \"@zodios/express\";\nimport { z } from \"zod\";\n\nconst userApi = makeApi([\n {\n method: \"get\",\n path: \"/users/:id\", // auto detect :id and ask for it in apiClient get params\n alias: \"getUser\", // optionnal alias to call this endpoint with it\n description: \"Get a user\",\n response: z.object({\n id: z.number(),\n name: z.string(),\n }),\n errors: [\n {\n status: 404,\n response: z.object({\n code: z.string(),\n message: z.string(),\n id: z.number(),\n }),\n }, {\n status: 'default', // default status code will be used if error is not 404\n response: z.object({\n code: z.string(),\n message: z.string(),\n }),\n },\n ],\n },\n]);\n\nconst app = zodiosApp(userApi);\napp.get(\"/users/:id\", (req, res) => {\n try {\n const id = +req.params.id;\n const user = service.findUser(id);\n if(!user) {\n // match error 404 schema with auto-completion\n res.status(404).json({\n code: \"USER_NOT_FOUND\",\n message: \"User not found\",\n id, // compile time error if you forget to add id\n });\n } else {\n // match response schema with auto-completion\n res.json(user);\n }\n } catch(err) {\n // match default error schema with auto-completion\n res.status(500).json({\n code: \"INTERNAL_ERROR\",\n message: \"Internal error\",\n });\n }\n})\n\napp.listen(3000);\n```\n\n# Roadmap\n\n- [] add support for swagger/openapi generation\n- [] add utilities to combine api declarations to match the express router api\n- [] add autocompletion for express `app.name()`\n","readmeFilename":"README.md"}
![\"Zodios](\"https://raw.githubusercontent.com/ecyrbe/zodios/main/docs/logo.svg\"){kind=logo}
\n \n ![\"langue](\"https://img.shields.io/npm/v/@zodios/express.svg\")
\n ![\"npm\"](\"https://img.shields.io/npm/dw/@zodios/express\")
\n ![\"GitHub\"](\"https://img.shields.io/github/license/ecyrbe/zodios-express\")
\n ![\"GitHub](\"https://img.shields.io/github/workflow/status/ecyrbe/zodios-express/CI\")
\n