{"id":13455284,"url":"https://github.com/ecyrbe/zodios","last_synced_at":"2025-05-13T16:06:33.900Z","repository":{"id":37043054,"uuid":"458816216","full_name":"ecyrbe/zodios","owner":"ecyrbe","description":"typescript http client and server with zod validation","archived":false,"fork":false,"pushed_at":"2025-04-05T02:28:09.000Z","size":7250,"stargazers_count":1782,"open_issues_count":18,"forks_count":49,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-08T23:13:35.154Z","etag":null,"topics":["api","http","nodejs","openapi","rest","typescript","zod"],"latest_commit_sha":null,"homepage":"https://www.zodios.org/","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":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ecyrbe"],"custom":["https://www.paypal.me/ecyrbe"]}},"created_at":"2022-02-13T13:23:51.000Z","updated_at":"2025-04-06T22:49:13.000Z","dependencies_parsed_at":"2022-07-11T15:33:28.857Z","dependency_job_id":"c4a761e9-171a-4efa-9bcd-88bd0a5ae91d","html_url":"https://github.com/ecyrbe/zodios","commit_stats":{"total_commits":768,"total_committers":28,"mean_commits":"27.428571428571427","dds":"0.39322916666666663","last_synced_commit":"6e6f3b3dbc3fdd62bc2c043efbdcd0254823fcb4"},"previous_names":[],"tags_count":188,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecyrbe","download_url":"https://codeload.github.com/ecyrbe/zodios/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250513380,"owners_count":21443200,"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":["api","http","nodejs","openapi","rest","typescript","zod"],"created_at":"2024-07-31T08:01:03.412Z","updated_at":"2025-04-23T20:43:56.673Z","avatar_url":"https://github.com/ecyrbe.png","language":"TypeScript","funding_links":["https://github.com/sponsors/ecyrbe","https://www.paypal.me/ecyrbe"],"categories":["TypeScript","Packages","api","APIs and Servers","**1. Libraries**"],"sub_categories":["Others"],"readme":" \u003ch1 align=\"center\"\u003eZodios\u003c/h1\u003e\n \u003cp align=\"center\"\u003e\n   \u003ca href=\"https://github.com/ecyrbe/zodios\"\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 is a typescript api client and an optional api server with auto-completion features backed by \u003ca href=\"https://axios-http.com\" \u003eaxios\u003c/a\u003e and \u003ca href=\"https://github.com/colinhacks/zod\"\u003ezod\u003c/a\u003e and \u003ca href=\"https://expressjs.com/\"\u003eexpress\u003c/a\u003e\n    \u003cbr/\u003e\n    \u003ca href=\"https://www.zodios.org/\"\u003eDocumentation\u003c/a\u003e\n \u003c/p\u003e\n \n \u003cp align=\"center\"\u003e\n   \u003ca href=\"https://www.npmjs.com/package/@zodios/core\"\u003e\n   \u003cimg src=\"https://img.shields.io/npm/v/@zodios/core.svg\" alt=\"langue typescript\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://www.npmjs.com/package/@zodios/core\"\u003e\n   \u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/dw/@zodios/core\"\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\"\u003e   \n   \u003c/a\u003e\n   \u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/ecyrbe/zodios/ci.yml?branch=main\"\u003e\n \u003c/p\u003e\n\u003cp align=\"center\"\u003e\n   \u003cimg alt=\"Bundle Size\" src=\"https://img.shields.io/bundlephobia/minzip/@zodios/core?label=%40zodios%2Fcore\"/\u003e\n   \u003cimg alt=\"Bundle Size\" src=\"https://img.shields.io/bundlephobia/minzip/@zodios/fetch?label=%40zodios%2Ffetch\"/\u003e\n   \u003cimg alt=\"Bundle Size\" src=\"https://img.shields.io/bundlephobia/minzip/@zodios/axios?label=%40zodios%2Faxios\"/\u003e\n   \u003cimg alt=\"Bundle Size\" src=\"https://img.shields.io/bundlephobia/minzip/@zodios/react?label=%40zodios%2Freact\"/\u003e\n   \u003cimg alt=\"Bundle Size\" src=\"https://img.shields.io/bundlephobia/minzip/@zodios/express?label=%40zodios%2Fexpress\"/\u003e\n   \u003cimg alt=\"Bundle Size\" src=\"https://img.shields.io/bundlephobia/minzip/@zodios/openapi?label=%40zodios%2Fopenapi\"/\u003e\n   \u003cimg alt=\"Bundle Size\" src=\"https://img.shields.io/bundlephobia/minzip/@zodios/testing?label=%40zodios%2Ftesting\"/\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 axios compatible API client and an optional expressJS compatible API server with the following features:  \n  \n- really simple centralized API declaration\n- typescript autocompletion in your favorite IDE for URL and parameters\n- typescript response types\n- parameters and responses schema thanks to zod\n- response schema validation\n- powerfull plugins like `fetch` adapter or `auth` automatic injection\n- all axios features available\n- `@tanstack/query` wrappers for react and solid (vue, svelte, etc, soon)\n- all expressJS features available (middlewares, etc.)\n\n  \n**Table of contents:**\n\n- [What is it ?](#what-is-it-)\n- [Install](#install)\n  - [Client and api definitions :](#client-and-api-definitions-)\n  - [Server :](#server-)\n- [How to use it on client side ?](#how-to-use-it-on-client-side-)\n  - [Declare your API with zodios](#declare-your-api-with-zodios)\n  - [API definition format](#api-definition-format)\n- [Full documentation](#full-documentation)\n- [Ecosystem](#ecosystem)\n- [Roadmap](#roadmap)\n- [Dependencies](#dependencies)\n\n# Install\n\n## Client and api definitions :\n\n```bash\n\u003e npm install @zodios/core\n```\n\nor\n\n```bash\n\u003e yarn add @zodios/core\n```\n\n## Server :\n  \n```bash\n\u003e npm install @zodios/core @zodios/express\n```\n\nor\n\n```bash\n\u003e yarn add @zodios/core @zodios/express\n```\n\n# How to use it on client side ?\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## Declare your API with zodios\n\nHere is an example of API declaration with Zodios.\n  \n```typescript\nimport { Zodios } from \"@zodios/core\";\nimport { z } from \"zod\";\n\nconst apiClient = new Zodios(\n  \"https://jsonplaceholder.typicode.com\",\n  // API definition\n  [\n    {\n      method: \"get\",\n      path: \"/users/:id\", // auto detect :id and ask for it in apiClient get params\n      alias: \"getUser\", // optional 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```\n\nCalling this API is now easy and has builtin autocomplete features :  \n  \n```typescript\n//   typed                     auto-complete path   auto-complete params\n//     ▼                               ▼                   ▼\nconst user = await apiClient.get(\"/users/:id\", { params: { id: 7 } });\nconsole.log(user);\n```\n  \nIt should output  \n  \n```js\n{ id: 7, name: 'Kurtis Weissnat' }\n```\nYou can also use aliases :\n  \n```typescript\n//   typed                     alias   auto-complete params\n//     ▼                        ▼                ▼\nconst user = await apiClient.getUser({ params: { id: 7 } });\nconsole.log(user);\n```\n## API definition format\n\n```typescript\ntype ZodiosEndpointDescriptions = Array\u003c{\n  method: 'get'|'post'|'put'|'patch'|'delete';\n  path: string; // example: /posts/:postId/comments/:commentId\n  alias?: string; // example: getPostComments\n  immutable?: boolean; // flag a post request as immutable to allow it to be cached with react-query\n  description?: string;\n  requestFormat?: 'json'|'form-data'|'form-url'|'binary'|'text'; // default to json if not set\n  parameters?: Array\u003c{\n    name: string;\n    description?: string;\n    type: 'Path'|'Query'|'Body'|'Header';\n    schema: ZodSchema; // you can use zod `transform` to transform the value of the parameter before sending it to the server\n  }\u003e;\n  response: ZodSchema; // you can use zod `transform` to transform the value of the response before returning it\n  status?: number; // default to 200, you can use this to override the sucess status code of the response (only usefull for openapi and express)\n  responseDescription?: string; // optional response description of the endpoint\n  errors?: Array\u003c{\n    status: number | 'default';\n    description?: string;\n    schema: ZodSchema; // transformations are not supported on error schemas\n  }\u003e;\n}\u003e;\n```\n# Full documentation\n\nCheck out the [full documentation](https://www.zodios.org) or following shortcuts.\n\n- [API definition](https://www.zodios.org/docs/category/zodios-api-definition)\n- [Http client](https://www.zodios.org/docs/category/zodios-client)\n- [React hooks](https://www.zodios.org/docs/client/react)\n- [Solid hooks](https://www.zodios.org/docs/client/solid)\n- [API server](http://www.zodios.org/docs/category/zodios-server)\n- [Nextjs integration](http://www.zodios.org/docs/server/next)\n\n# Ecosystem\n\n- [openapi-zod-client](https://github.com/astahmer/openapi-zod-client): generate a zodios client from an openapi specification\n- [@zodios/express](https://github.com/ecyrbe/zodios-express): full end to end type safety like tRPC, but for REST APIs\n- [@zodios/plugins](https://github.com/ecyrbe/zodios-plugins) : some plugins for zodios\n- [@zodios/react](https://github.com/ecyrbe/zodios-react) : a react-query wrapper for zodios\n- [@zodios/solid](https://github.com/ecyrbe/zodios-solid) : a solid-query wrapper for zodios\n\n# Roadmap for v11\n\nfor Zod` / `Io-Ts` :\n\n  - By using the TypeProvider pattern we can now make zodios validation agnostic.\n\n  - Implement at least ZodTypeProvider and IoTsTypeProvider since they both support `input` and `output` type inferrence\n\n  - openapi generation will only be compatible with zod though\n\n  - Not a breaking change so no codemod needed\n\n- [x] MonoRepo:\n\n  - Zodios will become a really large project so maybe migrate to turbo repo + pnpm\n\n  - not a breaking change\n\n- [ ] Transform:\n\n  - By default, activate transforms on backend and disable on frontend (today it's the opposite), would make server transform code simpler since with this option we could make any transforms activated not just zod defaults.\n\n  - Rationale being that transformation can be viewed as business code that should be kept on backend\n\n  - breaking change =\u003e codemod to keep current defaults by setting them explicitly\n\n- [x] Axios:\n\n  - Move Axios client to it's own package `@zodios/axios` and keep `@zodios/core` with only common types and helpers\n\n  - Move plugins to `@zodios/axios-plugins`\n\n  - breaking change =\u003e easy to do a codemod for this\n\n- [x] Fetch:\n\n  - Create a new Fetch client with almost the same features as axios, but without axios dependency `@zodios/fetch`\n\n  - Today we have fetch support with a plugin for axios instance (zodios maintains it's own axios network adapter for fetch). But since axios interceptors are not used by zodios plugins, we can make fetch implementation lighter than axios instance.\n\n  - Create plugins package `@zodios/fetch-plugins`\n\n  - Not sure it's doable without a lot of effort to keep it in sync/compatible with axios client\n\n  - new feature, so no codemod needed\n\n- [ ] React/Solid:  \n\n   - make ZodiosHooks independant of Zodios client instance (axios, fetch)\n\n   - not a breaking change, so no codemod needed\n\n- [x] Client Request Config\n\n  - uniform Query/Mutation with body sent on the config and not as a standalone object. This would allow to not do `client.deleteUser(undefined, { params: { id: 1 } })` but simply  `client.deleteUser({ params: { id: 1 } })`\n\n  - breaking change, so a codemod would be needed, but might be difficult to implement\n\n- [x] Mock/Tests:\n\n  - if we implement an abstraction layer for client instance, relying on moxios to mock APIs response will likely not work for fetch implementation.\n\n  - create a `@zodios/testing` package that work for both axios/fetch clients\n\n  - new feature, so no breaking change (no codemod needed)\n\nYou have other ideas ? [Let me know !](https://github.com/ecyrbe/zodios/discussions)\n# Dependencies\n\nZodios even when working in pure Javascript is better suited to be working with Typescript Language Server to handle autocompletion.\nSo you should at least use the one provided by your IDE (vscode integrates a typescript language server)\nHowever, we will only support fixing bugs related to typings for versions of Typescript Language v4.5\nEarlier versions should work, but do not have TS tail recusion optimisation that impact the size of the API you can declare.\n\nAlso note that Zodios do not embed any dependency. It's your Job to install the peer dependencies you need.  \n  \nInternally Zodios uses these libraries on all platforms :\n- zod\n- axios\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecyrbe%2Fzodios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecyrbe%2Fzodios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecyrbe%2Fzodios/lists"}