A lightweight, Web standards-based OpenAPI toolkit for TypeScript.
Generate types and a runtime contract from OpenAPI 3.0, 3.1, or 3.2. Make typed requests with native Fetch and consume streams through Web Streams. The generated module and optional openapi-shape/client have no runtime dependencies.
Warning
This project is in 0.x development. Public APIs and generated output may change incompatibly between minor versions. Pin your dependency version and review changes before upgrading.
You need Node.js 22 or later to generate a module. The client needs an ES module environment with Fetch and Web Streams.
Save your OpenAPI JSON or YAML description as openapi.yaml. The example below uses the Petstore description.
pnpm add openapi-shape
pnpm exec openapi-shape ./openapi.yaml -o src/api.tsImport the generated contract and set baseURL to your API's address. Adjust the import path to match your generated file:
import { createClient } from "openapi-shape/client"
import { contract } from "./api"
const api = createClient(contract, {
baseURL: "https://api.example.com/v1",
})
const { data, error, status } = await api.result("GET /pets", {
query: { limit: 10 },
})
if (error !== undefined) throw new Error(`HTTP ${status}`, { cause: error })
console.log(data.map((pet) => pet.name))Endpoint keys such as GET /pets select the request and response types. When using your own description, use its declared endpoints and parameters.
| Method | Use it to | Body ownership |
|---|---|---|
api.result() |
Decode a complete, non-streaming response | The client reads it; inspect status, data, error, and response headers. |
api.stream() |
Consume SSE messages or JSON records as a ReadableStream |
The subscription reads it; cancel when finished. |
api.fetch() |
Work with a typed native Response from any callable endpoint |
You read or cancel it. |
All three share typed inputs, request defaults, and middleware. You can also use the generated types with your own client.
Library-owned client failures use ClientError with a stable code and code-specific details. See error handling.
| Task | Guide |
|---|---|
| Generate a module, keep it current in CI, or use the JavaScript API | Generation |
| Send requests, handle responses, add middleware, or write typed wrappers | Client |
| Consume SSE, JSONL, NDJSON, or JSON Text Sequences | Streaming |
| Control parameters, forms, multipart uploads, and escaping | Serialization |
| Use schemas, endpoint types, webhooks, or callbacks directly | Generated module |
| Check supported features, reference rules, and type approximations | OpenAPI support |
For status narrowing, configured defaults, and generic wrappers, see type inference.