📘️ openapi-typescript-fetch
A typed fetch client for openapi-typescript
Install
npm install openapi-typescript-fetch
Or
yarn add openapi-typescript-fetch
Features
Supports JSON request and responses
Usage
Generate typescript definition from schema
npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output petstore.ts
# 🔭 Loading spec from https://petstore.swagger.io/v2/swagger.json…
# 🚀 https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]
Typed fetch client
import 'whatwg-fetch'
import { Fetcher } from 'openapi-typescript-fetch'
import { paths } from './petstore'
// declare fetcher for paths
const fetcher = Fetcher.for<paths>()
// global configuration
fetcher.configure({
baseUrl: 'https://petstore.swagger.io/v2',
init: {
headers: {
...
},
},
use: [...] // middlewares
})
// create fetch operations
const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create()
const addPet = fetcher.path('/pet').method('post').create()
// fetch
const { status, data: pets } = await findPetsByStatus({
status: ['available', 'pending'],
})
console.log(pets[0])
Typed Error Handling
A non-ok fetch response throws a generic ApiError
But an Openapi document can declare a different response type for each status code, or a default error response type
These can be accessed via a discriminated union on status, as in code snippet below
const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create()
const addPet = fetcher.path('/pet').method('post').create()
try {
await findPetsByStatus({ ... })
await addPet({ ... })
} catch(e) {
// check which operation threw the exception
if (e instanceof addPet.Error) {
// get discriminated union { status, data }
const error = e.getActualType()
if (error.status === 400) {
error.data.validationErrors // only available for a 400 response
} else if (error.status === 500) {
error.data.errorMessage // only available for a 500 response
} else {
...
}
}
}
Middleware
Middlewares can be used to pre and post process fetch operations (log api calls, add auth headers etc)
import { Middleware } from 'openapi-typescript-fetch'
const logger: Middleware = async (url, init, next) => {
console.log(`fetching ${url}`)
const response = await next(url, init)
console.log(`fetched ${url}`)
return response
}
fetcher.configure({
baseUrl: 'https://petstore.swagger.io/v2',
init: { ... },
use: [logger],
})
// or
fetcher.use(logger)
Server Side Usage
This library can be used server side with node-fetch
Node CommonJS setup
// install node-fetch v2
npm install node-fetch@2
npm install @types/node-fetch@2
// fetch-polyfill.ts
import fetch, { Headers, Request, Response } from 'node-fetch'
if (!globalThis.fetch) {
globalThis.fetch = fetch as any
globalThis.Headers = Headers as any
globalThis.Request = Request as any
globalThis.Response = Response as any
}
// index.ts
import './fetch-polyfill'
Utility Types
OpArgType - Infer argument type of an operationOpReturnType - Infer return type of an operationOpErrorType - Infer error type of an operationFetchArgType - Argument type of a typed fetch operationFetchReturnType - Return type of a typed fetch operationFetchErrorType - Error type of a typed fetch operationTypedFetch - Fetch operation type
import { paths, operations } from './petstore'
type Arg = OpArgType<operations['findPetsByStatus']>
type Ret = OpReturnType<operations['findPetsByStatus']>
type Err = OpErrorType<operations['findPetsByStatus']>
type Arg = OpArgType<paths['/pet/findByStatus']['get']>
type Ret = OpReturnType<paths['/pet/findByStatus']['get']>
type Err = OpErrorType<paths['/pet/findByStatus']['get']>
type FindPetsByStatus = TypedFetch<operations['findPetsByStatus']>
const findPetsByStatus = fetcher
.path('/pet/findByStatus')
.method('get')
.create()
type Arg = FetchArgType<typeof findPetsByStatus>
type Ret = FetchReturnType<typeof findPetsByStatus>
type Err = FetchErrorType<typeof findPetsByStatus>
Utility Methods
arrayRequestBody - Helper to merge params when request body is an array see issue
const body = arrayRequestBody([{ item: 1 }], { param: 2 })
// body type is { item: number }[] & { param: number }
Long numeric values (de)serialization: BigInt
Stringifying and parsing big numeric values could be problematic. JSON.parse will coerce large numeric values and JSON.stringify will throw an error: Uncaught TypeError: Do not know how to serialize a BigInt in such cases.
To circumvent this issue, this library will serialize big numeric values to BigInt using JSON.rawJSON, and equally parse big numeric values from responses via JSON.parse source text access transforming them to BigInt for you.
If you rely on the precision of big number in responses, or are sending big numeric values, make sure your JavaScript environment supports it. Read below...
JavaScript engine/environment support
TL;DR
Support is conditional; the TC39 proposal has reached staged 3 and has even shipped with Chrome by default already, with the rest of modern browsers soon to follow with their corresponding releases.
Regarding Node.js support; at least Node 20 is required to be run with the next harmony flag node --harmony-json-parse-with-source (or Node 21 without flag 🎉), until it is switched by default in future versions.
Happy fetching! 👍
