createFetch

Creates a fetch instance typed with an HTTP schema, mostly compatible with the native Fetch API. All requests and responses are typed by default with a schema, including methods, paths, status codes, arguments, and bodies.

createFetch<Schema>(options);

Arguments:

1. options: FetchOptions

   The options to create a fetch instance and use as defaults. They inherit from the native RequestInit interface, with the following additional properties:

   • baseURL: string

     The base URL for the fetch instance, which will be prepended to all request URLs.

   • searchParams: HttpSearchParamsSchema.Loose | undefined

     The default search parameters to be sent with each request.

   • onRequest: ((this: Fetch, request: FetchRequest.Loose) => Promise<Request> | Request) | undefined

     A listener that is called before each request is sent. See onRequest for more details.

   • onResponse: ((this: Fetch, response: FetchResponse.Loose) => Promise<Response> | Response) | undefined

     A listener that is called after each response is received. See onResponse for more details.

Type arguments:

1. Schema: HttpSchema

   The HTTP schema to use for the fetch instance.

Returns: Fetch

A fetch instance typed with the provided schema.

import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

type Schema = HttpSchema<{
  // ...
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

Related:

• Fetch API

onRequest

createFetch accepts an onRequest listener, which is a function that is called before sending each request.

onRequest(
  this: Fetch<Schema>,
  request: FetchRequest.Loose
): Promise<Request> | Request;

Arguments:

1. request: FetchRequest.Loose

   The request to send to the server.

Returns:

The request to use, either a modified version of the original request or a new one.

import { createFetch } from '@zimic/fetch';
import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        searchParams: { page?: number; limit?: number };
      };
      response: {
        200: { body: User[] };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:80',

  onRequest(request) {
    if (this.isRequest(request, 'GET', '/users')) {
      const url = new URL(request.url);
      url.searchParams.append('limit', '10');

      const updatedRequest = new Request(url, request);
      return updatedRequest;
    }

    return request;
  },
});

Related:

• fetch.onRequest API reference

onResponse

createFetch accepts an onResponse listener, which is a function that is called after receiving each response.

onResponse(
  this: Fetch<Schema>,
  response: FetchResponse.Loose
): Promise<Response> | Response;

Arguments:

1. response: FetchResponse.Loose

   The response received from the server.

Returns:

The response to use, either a modified version of the original response or a new one.

import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: {
        200: {
          headers: { 'content-encoding'?: string };
          body: User[];
        };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:80',

  onResponse(response) {
    if (this.isResponse(response, 'GET', '/users')) {
      console.log(response.headers.get('content-encoding'));
    }
    return response;
  },
});

Related:

• fetch.onResponse API reference