Zetch

HTTP Client with static type inference from your Zod Schemas

Table of contents

• Introduction
• Installation
• Usage
• Configs
  • AuthConfig
  • RetriesConfig
  • BaseZetchConfig
  • ZetchRequestConfig
  • ZetchClientConfig

Introduction

Zetch is a HTTP Client that allows you to get static type inference from your existing Zod schemas.

Zetch is designed to be as simple, light-weight and un-opinionated as possible. The goal is that this will eliminate the need for you to manually pass in types to your API calls. Instead, you can just pass in your Zod schema associated with the API call and get immediate static type inference.

Some key features of Zetch are:

• Static type inference - Zetch will infer the types of your API calls from your Zod schemas.
• Retries Configuration - Zetch will retry your API calls to your specified amount if they fail and they meet your specified status codes.
• Auth Configuration - Zetch allows you to configure your Authorization headers by providing your token and token scheme. If the request fails, your provided refeshToken function will run to get a new token prior to the retried request.
• Error logging - Zetch will log API errors or Schema Validation errors to your configured onError functions.
• Base Headers - Zetch allows you to configure your headers in a simple way for all of your calls for one client.
• Request Configuration - Zetch allows you to configure your specific requests within a Zetch Client.

Installation

1npm install zetch       # npm
2yarn add zetch          # yarn
3bun add zetch           # bun
4pnpm add zetch         # pnpm

Usage

Making a GET request

1// Create a schema for a Post
2const postSchema = z.object({
3    title: z.string(),
4    body: z.string(),
5    id: z.number(),
6    userId: z.number(),
7});
8
9// Make a request to get Posts with your schema provided to get static type inference
10await zetch.get('https://jsonplaceholder.typicode.com/posts', {
11    validationSchema: z.array(postSchema),
12});

Making a request with a body

1// Make a POST request with your body
2await zetch.post('/posts', {
3    body: {
4        title: 'foo',
5        body: 'bar',
6        userId: 1,
7        id: 1,
8    },
9});
10
11// Make a POST request with FormData
12const formData = new FormData();
13formData.append('title', 'foo');
14formData.append('body', 'bar');
15formData.append('userId', '1');
16formData.append('id', '1');
17
18await zetch.post('/posts', {
19    body: formData,
20});

Creating an API client and making a request

1// Create a Zetch Client with a Base Url
2const zetchClient = zetch.create({
3  baseUrl: 'https://jsonplaceholder.typicode.com',
4});
5
6// Create a schema for a Post
7const postSchema = z.object({
8  title: z.string(),
9  body: z.string(),
10  id: z.number(),
11  userId: z.number(),
12});
13
14// Make a request to get Posts with your schema provided to get static type inference
15const result = await zetchClient.get('/posts', {
16  validationSchema: z.array(postSchema),
17});

Configs

AuthConfig

AuthConfig is used to configure the Authorization header for your requests and add in refreshing your token prior to a retried request.

1interface AuthConfig {
2  // The function you'd like called to refresh the token
3  refreshToken?: () => Promise<string>;
4  // The token scheme you'd like to use (Basic, Bearer, JWTBearer)
5  tokenScheme: TokenScheme;
6  // Function to return the token you'd like to use
7  token: () => string;
8}

RetriesConfig

Retries Config allows you to configure the number of retries and status codes for retries.

1interface RetriesConfig {
2  // Status codes you'd like to retry on
3  retryStatuses: number[];
4  // The max number of retries you'd like to allow
5  numberOfRetries?: number;
6}

BaseZetchConfig

Base Zetch Config that's utilized for both requests and creating an API client

1interface BaseZetchConfig {
2  headers?: Headers;
3
4  // Configuration for authentication
5  authConfig?: AuthConfig;
6
7  // Configuration for retries
8  retriesConfig?: RetriesConfig;
9
10  // The function you'd like to use to log API errors to your error service of choice
11  onApiError?: (error: ZetchError) => void;
12
13  // The function you'd like to use to log API Validation errors to your error service of choice
14  onApiValidationError?: (error: ZodError) => void;
15}

ZetchRequestConfig

Configs for a Zetch Request

1// Config used for all Zetch Requests except for GET requests
2interface ZetchRequestConfig<ValidationSchema extends ZodFirstPartySchemaTypes>
3  extends BaseZetchConfig {
4  // The validation schema you'd like to use for the response
5  validationSchema?: ValidationSchema;
6
7  // The request body you'd like to send with the request
8  body?: FormData | unknown[] | { [key: string]: unknown };
9
10  // The abort controller you'd like to use for this request, in the event you would like to cancel the request
11  abortController?: AbortController;
12}
13
14// Config used for GET requests
15type ZetchGetRequestConfig<
16  ValidationSchema extends ZodFirstPartySchemaTypes
17> = Omit<ZetchRequestConfig<ValidationSchema>, 'body'>;

ZetchClientConfig

Config for your Zetch API Client from using zetch.create

1interface ZetchClientConfig extends BaseZetchConfig {
2  // The base url for your client
3  baseUrl: string;
4}