https://github.com/denosaurs/typefetch
📤 Magically generate `fetch` types from OpenAPI schemas for zero-cost browser-native api clients
https://github.com/denosaurs/typefetch
fetch openapi swagger typescript
Last synced: 7 months ago
JSON representation
📤 Magically generate `fetch` types from OpenAPI schemas for zero-cost browser-native api clients
- Host: GitHub
- URL: https://github.com/denosaurs/typefetch
- Owner: denosaurs
- License: mit
- Created: 2024-02-12T10:43:54.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-17T20:09:09.000Z (10 months ago)
- Last Synced: 2025-06-15T12:26:06.850Z (8 months ago)
- Topics: fetch, openapi, swagger, typescript
- Language: TypeScript
- Homepage: https://jsr.io/@denosaurs/typefetch
- Size: 137 KB
- Stars: 17
- Watchers: 2
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# TypeFetch
I dream of proper meta-programming in the wild west of ECMAScript. A parallel
universe where ECMAScript had types, macros, and a proper module system. Where
modules work regardless of environment and runtime. Where interfacing with the
system is standardized, and code from server runtimes work in the browser. But
alas, we are stuck in this bad joke of a universe where TypeScript is the next
best thing. So, I present to you, TypeFetch, a tool for generating zero-cost
type-safe `fetch` clients from OpenAPI schemas. It works everywhere you can call
`fetch`, and anywhere you can use TypeScript.
## Usage
To use TypeFetch, you need to have an OpenAPI schema. You can either provide a
local file path or a URL to the schema (which can be either json or yaml), then
all you need to do is run the cli using deno, node, or any other JavaScript
runtime supported by the [jsr](https://jsr.io) registry.
```sh
deno run -A jsr:@denosaurs/typefetch
```
```
Usage: typefetch [OPTIONS]
Options:
-h, --help Print this help message
-V, --version Print the version of TypeFetch
-o, --output Output file path (default: typefetch.d.ts)
--config File path to the tsconfig.json file
--import Import path for TypeFetch (default: https://raw.githubusercontent.com/denosaurs/typefetch/main)
--base-urls A comma separated list of custom base urls for paths to start with
--include-server-urls Include server URLs from the schema in the generated paths (default: true)
--include-absolute-url Include absolute URLs in the generated paths (default: false)
--include-relative-url Include relative URLs in the generated paths (default: false)
--experimental-urlsearchparams Enable the experimental fully typed URLSearchParams type (default: false)
```
## Example
```sh
deno run -A jsr:@denosaurs/typefetch https://api.jsr.io/.well-known/openapi
```
This will generate a `typefetch.d.ts` file in the current directory, which will
modify the global scope and the type definitions for the `fetch` function and
all types defined within the schema. For example:
```ts
declare global {
...
/**
* Returns a list of packages
* @summary List packages
*/
function fetch(
input: `https://api.jsr.io/packages` | `/packages`,
init?: Omit & {
method: "GET";
},
): Promise<
& Omit<
Response,
"ok" | "status" | "arrayBuffer" | "blob" | "formData" | "json" | "text"
>
& (
| ({
ok: true;
status: 200;
json(): Promise<{ items: Package[]; total: number }>;
text(): Promise>;
})
| ({
ok: false;
status: 400;
json(): Promise;
text(): Promise>;
})
)
>;
...
}
```
Which now allows you to use the `fetch` function with the
`https://api.jsr.io/packages` endpoint as following:
```ts
const response = await fetch("https://api.jsr.io/packages");
// The ok and status properties work as discriminators here to narrow the
// types of the response. That way the json and text methods are made
// type-safe.
if (response.ok) {
console.assert(response.status === 200);
const { items, total } = await response.json();
// even this works because we augment the global JSON object!
const { items, total } = JSON.parse(await response.text());
} else {
console.assert(response.status === 400);
const error = await response.json();
// or
const error = JSON.parse(await response.text());
}
```
## Maintainers
- Elias Sjögreen ([@eliassjogreen](https://github.com/eliassjogreen))
## Contributing
Pull request, issues and feedback are very welcome. Code style is formatted with
`deno fmt` and commit messages are done following Conventional Commits spec.
Please use it! And let us know if you have any issues, feedback or requests.
## Licence
Copyright 2024, the Denosaurs team. All rights reserved. MIT license.