getting‐started‐fetch

`@zimic/fetch` - Getting started

1. Requirements

Supported environments

If you are on the client side:
- Any relatively modern browser
If you are on the server side:
- Node >= 18.0.0

Supported languages

TypeScript >= 4.8
JavaScript >= ES6
- @zimic/fetch is fully functional on JavaScript, but consider using TypeScript for improved type safety and editor support.

If you are using TypeScript, we recommend enabling strict in your tsconfig.json:

{
  "compilerOptions": {
    "strict": true
  }
}

2. Installation

@zimic/fetch is available on npm.

Manager	Command
npm	`npm install @zimic/http @zimic/fetch --save-dev`
yarn	`yarn add @zimic/http @zimic/fetch --dev`
pnpm	`pnpm add @zimic/http @zimic/fetch --dev`

We also canary releases under the tag canary, containing the latest features and bug fixes:

Manager	Command
npm	`npm install @zimic/http@canary @zimic/fetch@canary --save-dev`
yarn	`yarn add @zimic/http@canary @zimic/fetch@canary --dev`
pnpm	`pnpm add @zimic/http@canary @zimic/fetch@canary --dev`

3. Create your fetch instance

Declare your HTTP schema using @zimic/http:

import { type HttpSchema } from '@zimic/http';

interface User {
  username: string;
}

interface RequestError {
  code: string;
  message: string;
}

type Schema = HttpSchema<{
  '/users': {
    POST: {
      request: { body: User };
      response: {
        201: { body: User };
        400: { body: RequestError };
        409: { body: RequestError };
      };
    };

    GET: {
      request: {
        searchParams: { query?: string; limit?: `${number}` };
      };
      response: {
        200: { body: User[] };
        400: { body: RequestError };
        401: { body: RequestError };
      };
    };
  };

  '/users/:userId': {
    PATCH: {
      request: {
        headers: { authorization: string };
        body: Partial<User>;
      };
      response: {
        204: {};
        400: { body: RequestError };
      };
    };
  };
}>;

You can also use zimic-http typegen to automatically generate types for your HTTP schema.

Create your fetch instance:

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

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

Enjoy requests and responses typed by default!

const response = await fetch('/users', {
  method: 'GET',
  searchParams: { query: 'u', limit: '10' },
});

if (response.status === 404) {
  return null; // User not found
}

if (!response.ok) {
  throw response.error;
}

const users = await response.json();
return users; // User[]