{"id":15645323,"url":"https://github.com/ecyrbe/zodios-express","last_synced_at":"2025-04-04T16:14:07.258Z","repository":{"id":57729245,"uuid":"525116653","full_name":"ecyrbe/zodios-express","owner":"ecyrbe","description":"zodios express server","archived":false,"fork":false,"pushed_at":"2025-03-27T07:23:16.000Z","size":791,"stargazers_count":56,"open_issues_count":6,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-27T08:29:41.952Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ecyrbe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-15T19:41:29.000Z","updated_at":"2024-12-15T10:00:14.000Z","dependencies_parsed_at":"2024-04-09T09:27:50.336Z","dependency_job_id":"a5d3ede4-e057-4c85-a314-860f55871db2","html_url":"https://github.com/ecyrbe/zodios-express","commit_stats":{"total_commits":341,"total_committers":5,"mean_commits":68.2,"dds":"0.29325513196480935","last_synced_commit":"f4f6c45eb99814fa74309bfae012c100352cc1a5"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecyrbe","download_url":"https://codeload.github.com/ecyrbe/zodios-express/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208143,"owners_count":20901570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T12:06:22.889Z","updated_at":"2025-04-04T16:14:07.228Z","avatar_url":"https://github.com/ecyrbe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":" \u003ch1 align=\"center\"\u003eZodios Express\u003c/h1\u003e\n \u003cp align=\"center\"\u003e\n   \u003ca href=\"https://github.com/ecyrbe/zodios-express\"\u003e\n     \u003cimg align=\"center\" src=\"https://raw.githubusercontent.com/ecyrbe/zodios/main/docs/logo.svg\" width=\"128px\" alt=\"Zodios logo\"\u003e\n   \u003c/a\u003e\n \u003c/p\u003e\n \u003cp align=\"center\"\u003e\n    Zodios express is a typescript end to end typesafe adapter for express using \u003ca href=\"https://github.com/colinhacks/zod\"\u003ezod\u003c/a\u003e\n    \u003cbr/\u003e\n \u003c/p\u003e\n \n \u003cp align=\"center\"\u003e\n   \u003ca href=\"https://www.npmjs.com/package/@zodios/express\"\u003e\n   \u003cimg src=\"https://img.shields.io/npm/v/@zodios/express.svg\" alt=\"langue typescript\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://www.npmjs.com/package/@zodios/express\"\u003e\n   \u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/dw/@zodios/express\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://github.com/ecyrbe/zodios/blob/main/LICENSE\"\u003e\n    \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/ecyrbe/zodios-express\"\u003e   \n   \u003c/a\u003e\n   \u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/workflow/status/ecyrbe/zodios-express/CI\"\u003e\n \u003c/p\u003e\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\u003e npm install @zodios/express\n```\n\nor\n\n```bash\n\u003e 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) =\u003e {\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) =\u003e {\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecyrbe%2Fzodios-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecyrbe%2Fzodios-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecyrbe%2Fzodios-express/lists"}