Introduction

what-the-fetch is a type-safe API client library that integrates schema validation with fetch requests, leveraging the Standard Schema specification for maximum flexibility and type safety.

Why what-the-fetch?#

Building API clients manually is tedious and error-prone. what-the-fetch solves common problems developers face when working with APIs:

Problems with Manual API Clients#

• 🔴 No type safety: Response types are unknown, leading to runtime errors
• 🔴 Manual validation: You need to write validation code for every endpoint
• 🔴 Schema duplication: Types and validation logic are often duplicated
• 🔴 URL building errors: String concatenation leads to malformed URLs
• 🔴 Poor developer experience: No autocomplete, no compile-time checks

How what-the-fetch Solves These Issues#

what-the-fetch provides a complete solution for type-safe API clients:

1. End-to-end type safety:

   • Full TypeScript inference from schema to response
   • Compile-time validation of requests
   • Autocomplete for all API endpoints and parameters
   • Type-safe path and query parameters

2. Schema validation:

   • Built-in support for Standard Schema specification
   • Works with Zod, Valibot, ArkType, and more
   • Automatic request/response validation
   • Single source of truth for types and validation

3. Clean API:

   • Simple, intuitive interface
   • Integrated with fast-url library for clean URL construction
   • Minimal boilerplate code
   • Focus on developer experience

4. Production-ready:

   • Comprehensive test coverage
   • Small bundle size
   • Battle-tested in real-world applications
   • Regular updates and maintenance

Key Features#

The Problem#

Building API clients manually lacks type safety and validation:

// ❌ No type safety, manual validationconst response = await fetch(`${baseUrl}/users/${id}?fields=${fields}`);const data = await response.json();// What type is data? Who knows! Runtime errors waiting to happen

Issues with manual API clients:

• 🔴 No type safety for request parameters
• 🔴 Unknown response types
• 🔴 Manual validation required
• 🔴 Schema and types are duplicated
• 🔴 Difficult to maintain and refactor

The Solution#

what-the-fetch provides a type-safe API client with automatic validation:

// ✅ Type-safe with validationimport { createFetch } from 'what-the-fetch';import { z } from 'zod';const api = {  '/users/:id': {    params: z.object({ id: z.number() }),    query: z.object({ fields: z.string().optional() }),    response: z.object({ id: z.number(), name: z.string(), email: z.string() })  }};const apiFetch = createFetch(api, baseUrl);const user = await apiFetch('/users/:id', {  params: { id },  query: { fields }});// user is fully typed as { id: number; name: string; email: string }

Benefits:

• ✅ Full end-to-end type safety
• ✅ Automatic request/response validation
• ✅ Single source of truth for types and validation
• ✅ Clean separation of concerns
• ✅ Easy to read and maintain

When to Use what-the-fetch#

what-the-fetch is ideal for:

• 🌐 REST API clients: Building type-safe wrappers around REST APIs
• 🔗 Microservices: Creating typed clients for service-to-service communication
• 📱 Frontend applications: Type-safe data fetching with validation
• 🛠️ Backend services: Calling external APIs with full type safety
• 📊 SDK development: Building SDKs with excellent developer experience

Quick Example#

Here's a real-world example showing how what-the-fetch simplifies API client development:

import { createFetch } from 'what-the-fetch';import { z } from 'zod';// Define API schema once (methods inferred automatically)const api = {  '/users/:id': {  // GET (no body)    params: z.object({ id: z.number() }),    query: z.object({ fields: z.string().optional() }),    response: z.object({      id: z.number(),      name: z.string(),      email: z.string()    })  },  '/users': {  // POST (has body)    body: z.object({ name: z.string(), email: z.string() }),    response: z.object({ id: z.number(), name: z.string() })  }};const apiFetch = createFetch(api, 'https://api.example.com');// Type-safe GET request with validationconst user = await apiFetch('/users/:id', {  params: { id: 123 },  query: { fields: 'name,email' }});// user is typed as { id: number; name: string; email: string }// Type-safe POST request (method inferred from body)const newUser = await apiFetch('/users', {  body: { name: 'John', email: 'john@example.com' }});

// Define types manuallyinterface User {  id: number;  name: string;  email: string;}// Build URL manuallyconst url = `https://api.example.com/users/${id}?fields=${fields}`;const response = await fetch(url);if (!response.ok) {  throw new Error(`HTTP error! status: ${response.status}`);}const data = await response.json();// Manual validation requiredif (typeof data.id !== 'number' ||     typeof data.name !== 'string' ||     typeof data.email !== 'string') {  throw new Error('Invalid response');}const user: User = data;// No compile-time guarantees that data matches User type