what-the-fetch

https://fetch.khanh.id/docs
Admin
what-the-fetch is a type-safe API client library that integrates schema validation with fetch...
Tokens:17,755
Snippets:144
Trust Score:4.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install what-the-fetch with Bun

Source: https://fetch.khanh.id/docs/getting-started

Install the what-the-fetch package using the Bun package manager.

```bash
bun add what-the-fetch
```

--------------------------------

### Install what-the-fetch with Deno

Source: https://fetch.khanh.id/docs/getting-started

Install the what-the-fetch package for Deno using JSR.

```bash
deno add jsr:@hckhanh/what-the-fetch
```

--------------------------------

### Install what-the-fetch with Yarn

Source: https://fetch.khanh.id/docs/getting-started

Install the what-the-fetch package using the Yarn package manager.

```bash
yarn add what-the-fetch
```

--------------------------------

### Install what-the-fetch with pnpm

Source: https://fetch.khanh.id/docs/getting-started

Install the what-the-fetch package using the pnpm package manager.

```bash
pnpm add what-the-fetch
```

--------------------------------

### Install what-the-fetch with npm

Source: https://fetch.khanh.id/docs/getting-started

Install the what-the-fetch package using the npm package manager.

```bash
npm install what-the-fetch
```

--------------------------------

### Complete API Reference Example

Source: https://fetch.khanh.id/docs/api-reference

This comprehensive example demonstrates defining various API endpoints with explicit HTTP methods, parameters, request bodies, and responses using what-the-fetch and Zod. It also shows how to instantiate the fetch client and make requests.

```javascript
import { createFetch } from 'what-the-fetch';
import { z } from 'zod';

const api = {
  // GET - Retrieve a user
  '@get/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  },
  
  // POST - Create a new user
  '@post/users': {
    body: z.object({
      name: z.string(),
      email: z.string().email()
    }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  },
  
  // PUT - Replace entire user
  '@put/users/:id': {
    params: z.object({ id: z.number() }),
    body: z.object({
      name: z.string(),
      email: z.string().email()
    }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  },
  
  // PATCH - Partially update user
  '@patch/users/:id': {
    params: z.object({ id: z.number() }),
    body: z.object({
      name: z.string().optional(),
      email: z.string().email().optional()
    }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  },
  
  // DELETE - Remove a user
  '@delete/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ success: z.boolean() })
  }
} as const;

const apiFetch = createFetch(api, 'https://api.example.com');

// Make requests with explicit methods
const user = await apiFetch('@get/users/:id', { params: { id: 123 } });
// GET https://api.example.com/users/123

const newUser = await apiFetch('@post/users', {
  body: { name: 'John Doe', email: 'john@example.com' }
});
// POST https://api.example.com/users

await apiFetch('@put/users/:id', {
  params: { id: 123 },
  body: { name: 'Jane Doe', email: 'jane@example.com' }
});
// PUT https://api.example.com/users/123

await apiFetch('@patch/users/:id', {
  params: { id: 123 },
  body: { name: 'Jane Smith' }
});
// PATCH https://api.example.com/users/123

await apiFetch('@delete/users/:id', { params: { id: 123 } });
// DELETE https://api.example.com/users/123
```

--------------------------------

### Equivalence of Implicit and Explicit HTTP Methods

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates that explicit method prefixes like @get are optional when the method can be inferred (GET for no body, POST for body). This snippet shows equivalent configurations and usage examples.

```javascript
const api = {
  // These two are identical - both use GET
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  '@get/users/:id': {  // Same as above - @get is optional
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  
  // POST is inferred from body
  '/users': {
    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');

// Both calls are equivalent - both use GET
const user1 = await apiFetch('/users/:id', { params: { id: 123 } });
const user2 = await apiFetch('@get/users/:id', { params: { id: 123 } });

// POST (inferred from body)
const newUser = await apiFetch('/users', {
  body: { name: 'John', email: 'john@example.com' }
});
```

--------------------------------

### Install Valibot for Schema Validation

Source: https://fetch.khanh.id/docs/getting-started

Install the Valibot library for schema validation, a requirement for what-the-fetch.

```bash
npm install valibot
```

--------------------------------

### Install Zod for Schema Validation

Source: https://fetch.khanh.id/docs/getting-started

Install the Zod library for schema validation, a requirement for what-the-fetch.

```bash
npm install zod
```

--------------------------------

### Install ArkType for Schema Validation

Source: https://fetch.khanh.id/docs/getting-started

Install the ArkType library for schema validation, a requirement for what-the-fetch.

```bash
npm install arktype
```

--------------------------------

### GET Request with Query Parameters

Source: https://fetch.khanh.id/docs/getting-started

Add query parameters to a GET request by defining the query schema. This example demonstrates optional query parameters for limiting and sorting results.

```typescript
const api = {
  '/users': {
    query: z.object({
      limit: z.number().optional(),
      offset: z.number().optional(),
      sort: z.string().optional()
    }),
    response: z.array(z.object({
      id: z.number(),
      name: z.string()
    }))
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const users = await apiFetch('/users', {
  query: { limit: 10, offset: 20, sort: 'name' }
});
// users is typed as Array<{ id: number; name: string }>
```

--------------------------------

### Example ApiPath Usage

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates extracting API paths from a defined API schema.

```typescript
const api = {
  '/users/:id': { /* ... */ },
  '/posts': { /* ... */ }
};

type Path = ApiPath<typeof api>;
// Path = '/users/:id' | '/posts'
```

--------------------------------

### Example FetchOptions Usage

Source: https://fetch.khanh.id/docs/api-reference

Shows how to infer the fetch options type for a given API path, including its parameters and query.

```typescript
const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    query: z.object({ fields: z.string().optional() })
  }
};

type Options = FetchOptions<typeof api, '/users/:id'>;
// Options = { params: { id: number }, query?: { fields?: string } }
```

--------------------------------

### Required Params Schema Example

Source: https://fetch.khanh.id/docs/api-reference

Illustrates the correct and incorrect ways to define API schemas when path parameters are present. The incorrect example is missing the mandatory `params` schema, which will lead to an error.

```javascript
// ❌ This will throw an error
const badApi = {
  '/users/:id': {
    response: z.object({ id: z.number(), name: z.string() })
    // Missing params schema!
  }
};

// ✅ This is correct
const goodApi = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  }
};
```

--------------------------------

### Explicit HTTP Method Usage

Source: https://fetch.khanh.id/docs/getting-started

Demonstrates how to explicitly specify HTTP methods like GET, PUT, PATCH, and DELETE using the '@method' prefix. Also shows that 'POST' is inferred when a body is present and 'GET' is inferred when no body is present.

```typescript
const api = {
  // Automatic inference - these are equivalent
  '/users/:id': {  // Uses GET (no body)
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  '@get/users/:id': {  // Explicit GET - same as above
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  
  // POST is inferred when body is present
  '/users': {  // Uses POST (has body)
    body: z.object({ name: z.string(), email: z.string().email() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  
  // Explicit methods for other HTTP verbs
  '@put/users/:id': {
    params: z.object({ id: z.number() }),
    body: z.object({ name: z.string() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  '@patch/users/:id': {
    params: z.object({ id: z.number() }),
    body: z.object({ name: z.string().optional() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  '@delete/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ success: z.boolean() })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

// These two are equivalent - both use GET
const user1 = await apiFetch('/users/:id', { params: { id: 123 } });
const user2 = await apiFetch('@get/users/:id', { params: { id: 123 } });

// POST inferred from body
const created = await apiFetch('/users', { body: { name: 'John', email: 'john@example.com' } });

// Explicit methods
await apiFetch('@put/users/:id', { params: { id: 123 }, body: { name: 'Jane' } });
await apiFetch('@patch/users/:id', { params: { id: 123 }, body: { name: 'Jane Doe' } });
await apiFetch('@delete/users/:id', { params: { id: 123 } });
```

--------------------------------

### Example API Schema Definition

Source: https://fetch.khanh.id/docs/api-reference

Illustrates how to define an API schema using Zod for path parameters, query parameters, and response validation.

```typescript
import { z } from 'zod';

const api: ApiSchema = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    query: z.object({ fields: z.string().optional() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  '/users': {
    // GET /users - List users with pagination
    query: z.object({
      limit: z.number().optional(),
      offset: z.number().optional()
    }),
    response: z.array(z.object({ id: z.number(), name: z.string() }))
  }
};
```

--------------------------------

### Example ApiData Usage for Params

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates extracting the type for URL path parameters from an API schema and path.

```typescript
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() })
  }
};

// Extract params type
type UserParams = ApiData<typeof api, '/users/:id', 'params'>;
// UserParams = { id: number }
```

--------------------------------

### Create Fetch Function with Parameterized Path Schema

Source: https://fetch.khanh.id/docs/getting-started

When using parameterized paths like '/users/:id', you must define a 'params' schema. This example sets up a fetch function for such a route.

```javascript
const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');
```

--------------------------------

### Example ApiData Usage for Query

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates extracting the type for query string parameters from an API schema and path.

```typescript
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() })
  }
};

// Extract query type
type UserQuery = ApiData<typeof api, '/users/:id', 'query'>;
// UserQuery = { fields?: string }
```

--------------------------------

### Type-Safe API Client with Validation (Solution)

Source: https://fetch.khanh.id/docs

Illustrates how to create a type-safe API client using what-the-fetch with automatic validation. This example shows schema definition using Zod and the creation of a typed fetch function.

```typescript
// ✅ Type-safe with validation
import { 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 }
```

--------------------------------

### Explicit HTTP Method Prefixes

Source: https://fetch.khanh.id/docs/api-reference

Use method prefixes like @get, @post, @put, @patch, and @delete for explicit control over HTTP methods or to specify methods other than GET and POST. This snippet demonstrates the syntax.

```javascript
const api = {
  '@get/resource': { /* Explicit GET - same as /resource */ },
  '/resource': { /* Implicit GET */ },
  '@post/resource': { /* Explicit POST */ },
  '@put/resource/:id': { /* PUT - prefix required */ },
  '@patch/resource/:id': { /* PATCH - prefix required */ },
  '@delete/resource/:id': { /* DELETE - prefix required */ }
};
```

--------------------------------

### Example ApiData Usage for Response

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates extracting the type for API response data from an API schema and path.

```typescript
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() })
  }
};

// Extract response type
type UserResponse = ApiData<typeof api, '/users/:id', 'response'>;
// UserResponse = { id: number; name: string }
```

--------------------------------

### Compile-Time Validation Examples

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates valid and invalid TypeScript calls to `apiFetch` that are caught at compile time.

```typescript
// ✅ This compiles
await apiFetch('/users/:id', { params: { id: 123 } });

// ❌ TypeScript error: Property 'params' is missing
await apiFetch('/users/:id', {});

// ❌ TypeScript error: Type 'string' is not assignable to type 'number'
await apiFetch('/users/:id', { params: { id: '123' } });

// ❌ TypeScript error: '/invalid' is not assignable to type '/users/:id' | ...
await apiFetch('/invalid', {});
```

--------------------------------

### Type-Safe GET Request with Parameters

Source: https://fetch.khanh.id/docs/getting-started

Make a type-safe GET request by defining request parameters and response schemas using Zod. The API endpoint and parameters are inferred.

```typescript
import { createFetch } from 'what-the-fetch';
import { z } from 'zod';

const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const user = await apiFetch('/users/:id', {
  params: { id: 123 }
});
// user is typed as { id: number; name: string; email: string }
```

--------------------------------

### Using Valibot for Schema Validation

Source: https://fetch.khanh.id/docs/getting-started

Integrate what-the-fetch with Valibot for defining API request parameters and response schemas. Ensure Valibot is installed and imported.

```typescript
import { createFetch } from 'what-the-fetch';
import * as v from 'valibot';

const api = {
  '/users/:id': {
    params: v.object({ id: v.number() }),
    response: v.object({ id: v.number(), name: v.string() })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');
```

--------------------------------

### Combining Path and Query Parameters

Source: https://fetch.khanh.id/docs/getting-started

Define and use API endpoints that accept both path parameters and optional query parameters. The example demonstrates how to construct the URL with both types of parameters.

```typescript
const api = {
  '/users/:id/posts': {
    params: z.object({ id: z.number() }),
    query: z.object({
      limit: z.number().optional(),
      published: z.boolean().optional()
    }),
    response: z.array(z.object({
      id: z.number(),
      title: z.string()
    }))
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const posts = await apiFetch('/users/:id/posts', {
  params: { id: 123 },
  query: { limit: 10, published: true }
});
// URL: https://api.example.com/users/123/posts?limit=10&published=true
```

--------------------------------

### GET - Retrieve a user

Source: https://fetch.khanh.id/docs/api-reference

Retrieves a specific user's details using their ID. This operation uses the GET method and requires the user's ID as a path parameter.

```APIDOC
## GET /users/:id

### Description
Retrieves a specific user's details using their ID. This operation uses the GET method and requires the user's ID as a path parameter.

### Method
GET

### Endpoint
/users/:id

### Parameters
#### Path Parameters
- **id** (number) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **id** (number) - The user's unique identifier.
- **name** (string) - The user's name.
- **email** (string) - The user's email address.

### Request Example
```json
{
  "id": 123
}
```

### Response Example
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}
```
```

--------------------------------

### Define API Schema and Create Fetch Function

Source: https://fetch.khanh.id/docs/getting-started

Define your API endpoints with request/response schemas and create a fetch instance. This example shows a POST request with a body and response schema.

```javascript
const api = {
  '/users': {
    body: z.object({
      name: z.string().min(3),
      email: z.string().email()
    }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');
```

--------------------------------

### Using Zod for Schema Validation

Source: https://fetch.khanh.id/docs/getting-started

Integrate what-the-fetch with Zod for defining API request parameters and response schemas. Ensure Zod is installed and imported.

```typescript
import { createFetch } from 'what-the-fetch';
import { z } from 'zod';

const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');
```

--------------------------------

### GET /users

Source: https://fetch.khanh.id/docs/api-reference

Retrieves a list of users. This endpoint supports optional query parameters for pagination and sorting.

```APIDOC
## GET /users

### Description
Retrieves a list of users. This endpoint supports optional query parameters for pagination and sorting.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **limit** (number) - Optional - The maximum number of users to return.
- **offset** (number) - Optional - The number of users to skip before starting to collect the result set.
- **sort** (string) - Optional - The field to sort the users by (e.g., 'name').

### Request Example
```javascript
const api = {
  '/users': {
    query: z.object({
      limit: z.number().optional(),
      offset: z.number().optional(),
      sort: z.string().optional()
    }),
    response: z.array(z.object({
      id: z.number(),
      name: z.string()
    }))
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const users = await apiFetch('/users', {
  query: { limit: 10, offset: 0, sort: 'name' }
});
// GET https://api.example.com/users?limit=10&offset=0&sort=name
```

### Response
#### Success Response (200)
- **id** (number) - The unique identifier of the user.
- **name** (string) - The name of the user.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Alice"
  },
  {
    "id": 2,
    "name": "Bob"
  }
]
```
```

--------------------------------

### GET Request with Path Parameters

Source: https://fetch.khanh.id/docs/api-reference

Use this snippet to fetch a resource by its ID. Ensure the API definition includes the ':id' parameter.

```typescript
const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const user = await apiFetch('/users/:id', {
  params: { id: 123 }
});
// GET https://api.example.com/users/123
```

--------------------------------

### Using ArkType for Schema Validation

Source: https://fetch.khanh.id/docs/getting-started

Integrate what-the-fetch with ArkType for defining API request parameters and response schemas. Ensure ArkType is installed and imported.

```typescript
import { createFetch } from 'what-the-fetch';
import { type } from 'arktype';

const api = {
  '/users/:id': {
    params: type({ id: 'number' }),
    response: type({ id: 'number', name: 'string' })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');
```

--------------------------------

### GET Request with Path and Query Parameters

Source: https://fetch.khanh.id/docs/api-reference

Combine path and query parameters to fetch specific resources with filtering. This is useful for retrieving related data, like posts for a user.

```typescript
const api = {
  '/users/:id/posts': {
    params: z.object({ id: z.number() }),
    query: z.object({
      limit: z.number().optional(),
      published: z.boolean().optional()
    }),
    response: z.array(z.object({
      id: z.number(),
      title: z.string()
    }))
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const posts = await apiFetch('/users/:id/posts', {
  params: { id: 123 },
  query: { limit: 10, published: true }
});
// GET https://api.example.com/users/123/posts?limit=10&published=true
```

--------------------------------

### Handling Schema Validation Errors for Responses

Source: https://fetch.khanh.id/docs/getting-started

This example shows how to catch errors that occur when the API response does not match the defined schema.

```javascript
try {
  const user = await apiFetch('/users/:id', { params: { id: 123 } });
} catch (error) {
  // Validation error if response doesn't match schema
  console.error('Invalid response:', error);
}
```

--------------------------------

### GET /users/:id

Source: https://fetch.khanh.id/docs/api-reference

Retrieves a specific user by their ID. This endpoint supports path parameters for the user ID.

```APIDOC
## GET /users/:id

### Description
Retrieves a specific user by their ID. This endpoint supports path parameters for the user ID.

### Method
GET

### Endpoint
/users/:id

### Parameters
#### Path Parameters
- **id** (number) - Required - The unique identifier of the user.

### Request Example
```javascript
const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const user = await apiFetch('/users/:id', {
  params: { id: 123 }
});
// GET https://api.example.com/users/123
```

### Response
#### Success Response (200)
- **id** (number) - The unique identifier of the user.
- **name** (string) - The name of the user.
- **email** (string) - The email address of the user.

#### Response Example
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### GET Request with Query Parameters

Source: https://fetch.khanh.id/docs/api-reference

Use this snippet to filter or paginate a list of resources. The 'query' object can include optional parameters like limit, offset, and sort.

```typescript
const api = {
  '/users': {
    query: z.object({
      limit: z.number().optional(),
      offset: z.number().optional(),
      sort: z.string().optional()
    }),
    response: z.array(z.object({
      id: z.number(),
      name: z.string()
    }))
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const users = await apiFetch('/users', {
  query: { limit: 10, offset: 0, sort: 'name' }
});
// GET https://api.example.com/users?limit=10&offset=0&sort=name
```

--------------------------------

### Create a Type-Safe Fetch Function

Source: https://fetch.khanh.id/docs/api-reference

Use `createFetch` to define a typed fetch function for your API schema. This example demonstrates creating a fetcher for a user endpoint with parameters and query options.

```typescript
import { 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, 'https://api.example.com');

const user = await apiFetch('/users/:id', {
  params: { id: 123 },
  query: { fields: 'name,email' }
});
// user is typed as { id: number; name: string; email: string }
```

--------------------------------

### Automatic HTTP Method Inference

Source: https://fetch.khanh.id/docs/api-reference

what-the-fetch infers POST for requests with a body and GET for requests without a body. This snippet shows the configuration for such inferences.

```javascript
const api = {
  '/users/:id': { /* Uses GET (no body) */ },
  '/users': { body: z.object({...}), /* Uses POST (has body) */ }
};
```

--------------------------------

### Building a Complete API Client

Source: https://fetch.khanh.id/docs/api-reference

Shows how to construct a full-fledged API client class using `createFetch`, encapsulating all endpoints and providing type-safe methods for interacting with the API.

```APIDOC
## Building a Complete API Client

```javascript
import { createFetch } from 'what-the-fetch';
import { z } from 'zod';

// Define comprehensive API schema
const api = {
  '/users': {
    // GET /users - List users with pagination
    query: z.object({
      page: z.number().optional(),
      limit: z.number().optional()
    }),
    response: z.object({
      users: z.array(z.object({
        id: z.number(),
        name: z.string()
      })),
      total: z.number()
    })
  },
  '/users/:id': {
    // GET /users/:id - Get user by ID
    params: z.object({ id: z.number() }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string(),
      createdAt: z.string()
    })
  },
  '/users/create': {
    // POST /users/create - Create new user
    body: z.object({
      name: z.string().min(3),
      email: z.string().email(),
      password: z.string().min(8)
    }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  },
  '/users/:id/update': {
    // PATCH /users/:id/update - Update user
    params: z.object({ id: z.number() }),
    body: z.object({
      name: z.string().min(3).optional(),
      email: z.string().email().optional()
    }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  }
} as const;

// Create client with shared configuration
class APIClient {
  private fetch;

  constructor(baseUrl: string, apiKey: string) {
    // Use shared headers for authentication
    this.fetch = createFetch(
      api,
      baseUrl,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );
  }

  async getUsers(page = 1, limit = 10) {
    // No need to pass auth header - it's shared
    return this.fetch('/users', { query: { page, limit } });
  }

  async getUser(id: number) {
    return this.fetch('/users/:id', { params: { id } });
  }

  async createUser(data: { name: string; email: string; password: string }) {
    return this.fetch('/users/create', { body: data });
  }

  async updateUser(id: number, data: { name?: string; email?: string }) {
    return this.fetch('/users/:id/update', { params: { id }, body: data });
  }
}

// Usage
const client = new APIClient('https://api.example.com', 'your-api-key');
const users = await client.getUsers(1, 20);
const user = await client.getUser(123);
```
```

--------------------------------

### Manual API Client Implementation (Without what-the-fetch)

Source: https://fetch.khanh.id/docs

Illustrates a manual approach to API client development without what-the-fetch, highlighting the need for manual type definitions, URL construction, and response validation. This method involves more boilerplate and potential for runtime errors.

```javascript
// Define types manually
interface User {
  id: number;
  name: string;
  email: string;
}

// Build URL manually
const 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 required
if (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
```

--------------------------------

### Method Prefix with Path Parameters

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates using method prefixes with path parameters for PUT requests. Ensure correct parameter and body structure for the API call.

```javascript
const api = {
  '@put/users/:userId/posts/:postId': {
    params: z.object({
      userId: z.number(),
      postId: z.number()
    }),
    body: z.object({ title: z.string(), content: z.string() }),
    response: z.object({ success: z.boolean() })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

await apiFetch('@put/users/:userId/posts/:postId', {
  params: { userId: 123, postId: 456 },
  body: { title: 'Updated', content: 'New content' }
});
// PUT https://api.example.com/users/123/posts/456
```

--------------------------------

### Import createFetch and Zod

Source: https://fetch.khanh.id/docs/getting-started

Import the necessary `createFetch` function from what-the-fetch and `z` from Zod for schema definition.

```typescript
import { createFetch } from 'what-the-fetch';
import { z } from 'zod'; // or your preferred schema library
```

--------------------------------

### Create a Basic Type-Safe Fetch Function

Source: https://fetch.khanh.id/docs/getting-started

Use the `createFetch` function from what-the-fetch to initialize your typed API client. This function takes your API schema and base URL as arguments.

```typescript
import { createFetch } from 'what-the-fetch';

const apiFetch = createFetch(api, 'https://api.blog.com');
```

--------------------------------

### API Fetch with Validation

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates how to set up an API with validation schemas for parameters and responses. This snippet shows a typical use case where a validation error is caught and logged.

```javascript
const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

// This will throw a validation error
try {
  await apiFetch('/users/:id', { params: { id: 'invalid' } });
} catch (error) {
  console.error(error.message); // "Validation failed: [...]"
}
```

--------------------------------

### Custom Headers and Options

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates how to include custom headers and other request options like cache and signal for API requests.

```APIDOC
## Custom Headers and Options

### Description
Demonstrates how to include custom headers and other request options like cache and signal for API requests.

### Method
(Applies to any HTTP method)

### Endpoint
(Applies to any endpoint)

### Parameters
#### Request Options
- **headers** (object) - Optional - An object containing custom headers to be sent with the request.
  - **Authorization** (string) - Example: 'Bearer token'
  - **X-Custom-Header** (string) - Example: 'value'
- **cache** (string) - Optional - Specifies caching directives (e.g., 'no-cache').
- **signal** (AbortSignal) - Optional - An AbortSignal to cancel the request.

### Request Example
```javascript
const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const user = await apiFetch(
  '/users/:id',
  { params: { id: 123 } },
  {
    headers: {
      'Authorization': 'Bearer token',
      'X-Custom-Header': 'value'
    },
    cache: 'no-cache',
    signal: abortController.signal
  }
);
```
```

--------------------------------

### Build a Complete API Client

Source: https://fetch.khanh.id/docs/api-reference

Construct a class to encapsulate API interactions, leveraging `createFetch` with shared configurations for authentication and defining methods for each API endpoint. This promotes a clean and organized API client.

```typescript
import { createFetch } from 'what-the-fetch';
import { z } from 'zod';

// Define comprehensive API schema
const api = {
  '/users': {
    // GET /users - List users with pagination
    query: z.object({
      page: z.number().optional(),
      limit: z.number().optional()
    }),
    response: z.object({
      users: z.array(z.object({
        id: z.number(),
        name: z.string()
      })),
      total: z.number()
    })
  },
  '/users/:id': {
    // GET /users/:id - Get user by ID
    params: z.object({ id: z.number() }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string(),
      createdAt: z.string()
    })
  },
  '/users/create': {
    // POST /users/create - Create new user
    body: z.object({
      name: z.string().min(3),
      email: z.string().email(),
      password: z.string().min(8)
    }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  },
  '/users/:id/update': {
    // PATCH /users/:id/update - Update user
    params: z.object({ id: z.number() }),
    body: z.object({
      name: z.string().min(3).optional(),
      email: z.string().email().optional()
    }),
    response: z.object({
      id: z.number(),
      name: z.string(),
      email: z.string()
    })
  }
} as const;

// Create client with shared configuration
class APIClient {
  private fetch;

  constructor(baseUrl: string, apiKey: string) {
    // Use shared headers for authentication
    this.fetch = createFetch(
      api,
      baseUrl,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );
  }

  async getUsers(page = 1, limit = 10) {
    // No need to pass auth header - it's shared
    return this.fetch('/users', { query: { page, limit } });
  }

  async getUser(id: number) {
    return this.fetch('/users/:id', { params: { id } });
  }

  async createUser(data: { name: string; email: string; password: string }) {
    return this.fetch('/users/create', { body: data });
  }

  async updateUser(id: number, data: { name?: string; email?: string }) {
    return this.fetch('/users/:id/update', { params: { id }, body: data });
  }
}

// Usage
const client = new APIClient('https://api.example.com', 'your-api-key');
const users = await client.getUsers(1, 20);
const user = await client.getUser(123);
```

--------------------------------

### Type-Safe API Client with what-the-fetch

Source: https://fetch.khanh.id/docs

Demonstrates creating a type-safe API client using what-the-fetch and Zod for schema definition. This approach centralizes API schema definition and provides automatic validation for requests and responses.

```typescript
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 validation
const 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' }
});
```

--------------------------------

### GET /users/:id/posts

Source: https://fetch.khanh.id/docs/api-reference

Retrieves a list of posts for a specific user. This endpoint supports path parameters for the user ID and query parameters for filtering.

```APIDOC
## GET /users/:id/posts

### Description
Retrieves a list of posts for a specific user. This endpoint supports path parameters for the user ID and query parameters for filtering.

### Method
GET

### Endpoint
/users/:id/posts

### Parameters
#### Path Parameters
- **id** (number) - Required - The unique identifier of the user whose posts are to be retrieved.

#### Query Parameters
- **limit** (number) - Optional - The maximum number of posts to return.
- **published** (boolean) - Optional - Filters posts to include only those that are published.

### Request Example
```javascript
const api = {
  '/users/:id/posts': {
    params: z.object({ id: z.number() }),
    query: z.object({
      limit: z.number().optional(),
      published: z.boolean().optional()
    }),
    response: z.array(z.object({
      id: z.number(),
      title: z.string()
    }))
  }
};

const apiFetch = createFetch(api, 'https://api.example.com');

const posts = await apiFetch('/users/:id/posts', {
  params: { id: 123 },
  query: { limit: 10, published: true }
});
// GET https://api.example.com/users/123/posts?limit=10&published=true
```

### Response
#### Success Response (200)
- **id** (number) - The unique identifier of the post.
- **title** (string) - The title of the post.

#### Response Example
```json
[
  {
    "id": 101,
    "title": "First Post"
  },
  {
    "id": 102,
    "title": "Second Post"
  }
]
```
```

--------------------------------

### Shared Request Configuration

Source: https://fetch.khanh.id/docs/api-reference

Demonstrates how to set shared request options, such as headers and cache settings, that apply to all requests made with the created fetch instance.

```APIDOC
## Shared Request Configuration

Use the third parameter of `createFetch()` to set shared options for all requests:

```javascript
import { createFetch } from 'what-the-fetch';
import { z } from 'zod';

const api = {
  '/users/:id': {
    params: z.object({ id: z.number() }),
    response: z.object({ id: z.number(), name: z.string() })
  },
  '/posts': {
    response: z.array(z.object({ id: z.number(), title: z.string() }))
  }
};

// Create fetch with shared headers that apply to all requests
const apiFetch = createFetch(
  api,
  'https://api.example.com',
  {
    headers: {
      'Authorization': 'Bearer my-token',
      'X-API-Version': '2.0'
    },
    cache: 'no-cache'
  }
);

// All requests automatically include shared headers
const user = await apiFetch('/users/:id', { params: { id: 123 } });
const posts = await apiFetch('/posts');

// Override or add additional headers per request
const userWithCustomHeader = await apiFetch(
  '/users/:id',
  { params: { id: 456 } },
  {
    headers: {
      'X-Custom-Header': 'value' // Merged with shared headers
    }
  }
);
```
```

--------------------------------

### POST - Create a new user

Source: https://fetch.khanh.id/docs/api-reference

Creates a new user with the provided name and email. This operation uses the POST method and expects user details in the request body.

```APIDOC
## POST /users

### Description
Creates a new user with the provided name and email. This operation uses the POST method and expects user details in the request body.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new user.
- **email** (string) - Required - The email address of the new user.

### Response
#### Success Response (200)
- **id** (number) - The newly created user's unique identifier.
- **name** (string) - The user's name.
- **email** (string) - The user's email address.

### Request Example
```json
{
  "name": "John Doe",
  "email": "john@example.com"
}
```

### Response Example
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}
```
```

--------------------------------

### Manual API Client (Problem)

Source: https://fetch.khanh.id/docs

Demonstrates the lack of type safety and manual validation required when building API clients manually. This approach is prone to runtime errors due to unknown response types.

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

--------------------------------

### Valid and Invalid POST Request with Schema Validation

Source: https://fetch.khanh.id/docs/getting-started

Demonstrates making a valid POST request and how an invalid request (due to body schema mismatch) would fail at runtime.

```javascript
// ✅ Valid request
const user = await apiFetch('/users', {
  body: {
    name: 'John Doe',
    email: 'john@example.com'
  }
});

// ❌ This would fail at runtime with validation error
try {
  await apiFetch('/users', {
    body: {
      name: 'Jo', // Too short
      email: 'invalid-email' // Invalid format
    }
  });
} catch (error) {
  console.error('Validation failed:', error);
}
```

--------------------------------

### Create Fetch Function with Shared Options

Source: https://fetch.khanh.id/docs/getting-started

Initialize the typed API client with shared options, such as default headers, that will be applied to all requests made with this client.

```typescript
const apiFetch = createFetch(
  api,
  'https://api.blog.com',
  {
    headers: {
      'Authorization': 'Bearer your-api-key'
    }
  }
);
```
Tokens:
Raw