Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/flock-community/zod-endpoints
Zod Router
https://github.com/flock-community/zod-endpoints
Last synced: 3 months ago
JSON representation
Zod Router
- Host: GitHub
- URL: https://github.com/flock-community/zod-endpoints
- Owner: flock-community
- License: mit
- Created: 2020-08-02T19:56:59.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2021-11-08T18:39:28.000Z (over 2 years ago)
- Last Synced: 2024-03-19T11:22:38.138Z (3 months ago)
- Language: TypeScript
- Size: 732 KB
- Stars: 163
- Watchers: 14
- Forks: 7
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- awesome-zod - `zod-endpoints` - Contract-first strictly typed endpoints with Zod. OpenAPI compatible. (APIs and Servers)
README
# Zod-endpoints
Contract first strictly typed endpoints. By defining endpoints as a zod schema, all the requests and responses can be checked and parsed at runtime. Moreover, the TypeScript compiler can check the in- and output types of the endpoints.
In this way the problem space of your application will become much smaller to begin with. By using zod-endpoints you can rely on the types during development and on validation at runtime. This yields requests and responses you can trust. The focus can shift more to defining business logic instead of input validation and error handling.
The schema can be used as a contract between consumer and producer. Drivers can be generated from the contract which ensures proper communication between a client and server.
## Example project
[Example](https://github.com/flock-community/zod-endpoints-example)
## Simplified model
Zod-endpoints is based on a type representation of a http schema. Below a simplyfied version of the model. The full model can be found [here](src/model.ts). The model is a union of requests which contains a union of response objects. Both request and response contain a union of body types.
````ts
type Body = {
type: "applictions/json" | "plain/html"
content: any
}
type Request = {
method: "GET" | "POST" | "PUT" | "DELETE"
path: [...string[]]
body: Body | ...Body
}
type Response = {
status: number
body: Body | ...Body
}
type Http = Request & {
responses: Response | ...Response
}
type Schema = Http | ...Http
````
## Getting started
First step is to define an endpoint by making use of the [zod-endpoints dsl](src/dsl.ts). Below you can find an example of a simple example. This example contains two endpoints to get and create a project.
### Define endpoints
````ts
import * as z from "zod-endpoints";
const project = z.object({
id: z.string().uuid(),
name: z.string(),
})
const schema = z.endpoints([
z.endpoint({
name: "GET_PROJECT",
method: "GET",
path: [z.literal("projects"), z.string().uuid()],
responses: [
z.response({
status: 200,
body:{
type: "application/json",
content: project
}
}),
],
}),
z.endpoint({
name: "CREATE_PROJECT",
method: "POST",
path: [z.literal("projects")],
body:{
type: "application/json",
content: project
},
responses: [
z.response({
status: 201,
}),
],
}),
]);
````
## Api
The endpoints can be convert into a service or a client with the [Api](src/api.ts) type.
### Server
For the type transforms the schema into an object of the requests. The key of the object is the name of the route the value is a function from the request to a union of the responses. This object is strict typed and exhaustive.
```ts
const service = {
findProjectById: (id:string):Project => {},
createProject: (project:Project) => {},
}
````
```ts
import * as z from "zod-endpoints";
const server: z.Api = {
"GET_PROJECT": ({path}) => findProjectById(path[1]).then(project => ({
status: 200,
body:{
type: "application/json",
content:project
}
})),
"CREATE_PROJECT": ({body}) => createProject(body).Promise.resolve({
status: 201
}),
};
```
### Client
The client implementation
```ts
const http = (req: z.ApiRequest) => {
fetch(req.path.join('/'), {
method: req.method
})
}
````
```ts
import * as z from "zod-endpoints";
const client: z.Api = {
"GET_PROJECT": (req) => http(req),
"CREATE_PROJECT": (req) => http(req)
};
```
## Documentation
Zod endpoints is fully compatible with [open api specification](https://www.openapis.org/). The schema can be transformed into open api json. For example with Swagger this can be presented as a documentation website.
```ts
const docs = z.openApi(schema)
````
