Fetch Schema

Fetch schema allows you to pre-define the url path and the shape of reqeust and response data. You can easily document your api using this schema.

The output of the scheam will be validated using zod and if the validation fails, it'll throw an error.

Before we start, make sure you have installed the zod package.

npm i zod

to create a fetch schema, you need to import the createSchema function from @better-fetch/fetch.

fetch.ts

import { createSchema, createFetch } from "@better-fetch/fetch";
import { z } from "zod";
 
 
export const schema = createSchema({ 
    "/path": { 
        input: z.object({ 
            userId: z.string(), 
            id: z.number(), 
            title: z.string(), 
            completed: z.boolean(), 
        }), 
        output: z.object({ 
            userId: z.string(), 
            id: z.number(), 
            title: z.string(), 
            completed: z.boolean(), 
        }), 
    } 
}) 
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    schema: schema 
});

Fetch Schema

The Fetch Schema is a map of path/url and schema. The path is the url path and the schema is an object with input, output, query and params keys.

The input key is the schema of the request data. The output key is the schema of the response data. The query key is the schema of the query params. The params key is dynamic path parameters.

The input schema is the schema of the request data. The input key is the schema of the request data. If you defined an input schema, the data will be requeired to be passed as a body of the request.

If you define an input schema, a post method will be used to make the request and if there is no input schema, a get method will be used. See method modifiers section for defining specefic methods.

fetch.ts

import { createFetch, createSchema } from "@better-fetch/fetch";
import { z } from "zod";
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    schema: createSchema({
        "/path": {
            input: z.object({
                userId: z.string(),
                id: z.number(),
                title: z.string(),
                completed: z.boolean(),
            }),
        },
    }), 
})
 
const { data, error } = await $fetch("/path", {
    body: {}Type '{}' is missing the following properties from type '{ userId: string; id: number; title: string; completed: boolean; }': userId, id, title, completed
})

To make the body optional you can wrap the schema with z.optional.

Output

The output schema is the schema of the response data. The output key is the schema of the response data. If you defined an output schema, the data will be returned as the response body.

fetch.ts

import { createFetch, createSchema } from "@better-fetch/fetch";
import { z } from "zod";
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    schema: createSchema({
        "/path": {
            output: z.object({
                userId: z.string(),
                id: z.number(),
                title: z.string(),
                completed: z.boolean(),
            }),
        },
    }), 
})
 
const { data, error } = await $fetch("/path")
 Hover over the data object to see the type

Query

The query schema is the schema of the query params. The query key is the schema of the query params. If you defined a query schema, the data will be passed as the query params.

fetch.ts

import { createFetch, createSchema } from "@better-fetch/fetch";
import { z } from "zod";
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    schema: createSchema({
        "/path": {
            query: z.object({
                userId: z.string(),
                id: z.number(),
                title: z.string(),
                completed: z.boolean(),
            }),
        },
    }), 
})
 
const { data, error } = await $fetch("/path", {  
    query: {}Type '{}' is missing the following properties from type '{ userId: string; id: number; title: string; completed: boolean; }': userId, id, title, completed
})
 Hover over the data object to see the type

Dynamic Path Parameters

The params schema is the schema of the path params. You can either use the params key to define the paramters or prepend : to the path to make the parameters dynamic.

If you define more than one dynamic path parameter using the string modifier the paramters will be required to be passed as an array of values in the order they are defined.

fetch.ts

import { createFetch, createSchema } from "@better-fetch/fetch";
import { z } from "zod";    
 
const schema = createSchema({
    "/user/:id": {
        output: z.object({
            name: z.string(),
        }),
    },
    "/post": {
        params: z.object({
            id: z.string(),
            title: z.string(),
        }),
    },
    "/post/:id/:title": {
        output: z.object({
            title: z.string(),
        }),
    }
}) 
 
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    schema: schema
})
 
const response1 = await $fetch("/user/:id", {
    params: {
        id: "1",
    }
})
 
const response2 = await $fetch("/post", {
    params: {
        id: "1",
        title: "title"
    },
})
 
const response3 = await $fetch("/post/:id/:title", {
    params: {
        id: "1",
        title: "title"
    }
})

Method Modifiers

By default the get and post methods are used to make the request based on weather the input schema is defined or not. You can use the method modifier to define the method to be used.

The method modifiers are @get, @post, @put, @patch, @delete and @head. You prepend the method name to the path to define the method

fetch.ts

import { createFetch, createSchema } from "@better-fetch/fetch";
import { z } from "zod";
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    schema: createSchema({
        "@put/user": { 
            input: z.object({
                title: z.string(),
                completed: z.boolean(),
            }),
            output: z.object({
               title: z.string(),
               completed: z.boolean(),
            }),
        },
    }), 
})
 
const { data, error } = await $fetch("/@put/user", {
    body: {
        title: "title",
        completed: true,
    }
})
 the request will be made to "/user" path with a PUT method.

Strict Schema

By default if you define schema better fetch still allows you to make a call to other routes that's not defined on the schema. If you want to enforce only the keys defined to be inferred as valid you can use pass the strict option to the schema.

fetch.ts

import { createFetch, createSchema } from "@better-fetch/fetch";
import { z } from "zod";
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    schema: createSchema({
        "/path": {
            output: z.object({
                userId: z.string(),
                id: z.number(),
                title: z.string(),
                completed: z.boolean(),
            }),
        },
    }, 
    { 
        strict: true
    }), 
})
const { data, error } = await $fetch("/invalid-path")Argument of type '"/invalid-path"' is not assignable to parameter of type '"/path"'.

Fetch Schema

Fetch Schema

Input

Output

Query

Dynamic Path Parameters

Method Modifiers

Strict Schema

On this page