Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/borolgs/openapi-ff
Generate typed effects and queries from OpenAPI 3
https://github.com/borolgs/openapi-ff
effector openapi openapi-typescript swagger
Last synced: about 2 months ago
JSON representation
Generate typed effects and queries from OpenAPI 3
- Host: GitHub
- URL: https://github.com/borolgs/openapi-ff
- Owner: borolgs
- License: mit
- Created: 2024-11-24T11:21:23.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2024-12-03T15:31:07.000Z (about 2 months ago)
- Last Synced: 2024-12-03T16:34:58.367Z (about 2 months ago)
- Topics: effector, openapi, openapi-typescript, swagger
- Language: TypeScript
- Homepage:
- Size: 40 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# openapi-ff
openapi-ff is a type-safe tiny wrapper around [effector](https://effector.dev/) and [farfetched](https://ff.effector.dev/) to work with OpenAPI schema.
It works by using [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) and [openapi-typescript](https://openapi-ts.dev/).
## Setup
```bash
pnpm i openapi-ff @farfetched/core effector openapi-fetch
pnpm i -D openapi-typescript typescript
```
Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:
```bash
npx openapi-typescript ./path/to/api/v1.yaml -o ./src/shared/api/schema.d.ts
```
## Usage
```ts
import createFetchClient from "openapi-fetch";
import { createClient } from "openapi-ff";
import { createQuery } from "@farfetched/core";
import type { paths } from "./schema"; // generated by openapi-typescript
export const client = createFetchClient({
baseUrl: "https://myapi.dev/v1/",
});
export const { createApiEffect } = createClient(client);
const blogpostQuery = createQuery({
effect: createApiEffect("get", "/blogposts/{post_id}"),
});
```
```tsx
import { useUnit } from "effector-react";
function Post() {
const { data: post, pending } = useUnit(blogpostQuery);
if (pending) {
return ;
}
return (
{post.title}
);
}
```
Advanced Usage:
```ts
import { chainRoute } from "atomic-router";
import { startChain } from "@farfetched/atomic-router";
import { isApiError } from "openapi-ff";
const getBlogpostFx = createApiEffect("get", "/blogposts/{post_id}", {
mapParams: (args: { postId: string }) => ({ params: { path: { post_id: args.postId } } }),
});
const blogpostQuery = createQuery({
effect: getBlogpostFx,
mapData: ({ result, params }) => ({ ...result, ...params }),
initialData: { body: "-", title: "-", postId: "0" },
});
export const blogpostRoute = chainRoute({
route: routes.blogpost.item,
...startChain(blogpostQuery),
});
const apiError = sample({
clock: softwareQuery.finished.failure,
filter: isApiError,
});
```
## Runtime Validation
`openapi-ff` does not handle runtime validation, as `openapi-typescript` [does not support it](https://github.com/openapi-ts/openapi-typescript/issues/1420#issuecomment-1792909086).
> openapi-typescript by its design generates runtime-free static types, and only static types.
However, `openapi-ff` allows adding a contract factory when creating a client and provides a corresponding method, `createApiEffectWithContract`:
```ts
const { createApiEffectWithContract } = createClient(fetchClient, {
createContract(method, path) {
// ... create your own contract
return contract; // Contract
},
});
const query = createQuery({
...createApiEffectWithContract("get", "/blogposts"),
});
```
### [typed-openapi](https://github.com/astahmer/typed-openapi) example
```bash
npx typed-openapi path/to/api.yaml -o src/zod.ts -r zod # Generate zod schemas
pnpm install zod @farfetched/zod
```
```ts
import { EndpointByMethod } from "./zod";
import { zodContract } from "@farfetched/zod";
const { createApiEffectWithContract } = createClient(fetchClient, {
createContract(method, path) {
const response = (EndpointByMethod as any)[method][path]?.response;
if (!response) {
throw new Error(`Response schema for route "${method} ${path}" doesn't exist`);
}
return zodContract(response);
},
});
const query = createQuery({
...createApiEffectWithContract("get", "/blogposts"),
});
```
### [orval](https://orval.dev/) example
Alternatively, you can simply add any contract to a query:
```bash
pnpm install zod @farfetched/zod
npx orval --input path/to/api.yaml --output src/zod.ts --client zod --mode single
```
```ts
import { zodContract } from "@farfetched/zod";
import { getBlogpostsResponseItem } from "./zod";
const blogpostQuery = createQuery({
effect: createApiEffect("get", "/blogposts/{post_id}"),
contract: zodContract(getBlogpostsResponseItem),
});
```
## TODO
Add `createApiQuery`:
```ts
createApiQuery({
method: "get",
path: "/blogposts/{post_id}",
mapParams: (args: { postId: string }) => ({ params: { path: { post_id: args.postId } } }),
mapData: ({ result, params }) => ({ ...result, ...params }),
initialData: { body: "-", title: "-", postId: "0" },
});
```