zimic-http

@zimic/http

TypeScript-first HTTP utilities

npm   •   Docs   •   Examples   •   Issues   •   Roadmap

     

 

---

• Features
• Getting started
  • Installation
• Basic usage
• Documentation
• Examples
• Changelog
• Contributing

---

@zimic/http is a collection of type-safe utilities to handle HTTP requests and responses, including headers, search params, and form data.

Note

🌱 This library is in beta.

Features

• ⭐ HTTP schemas and typegen: Declare the structure of your HTTP endpoints as a TypeScript schema and use it to type your HTTP requests and responses. If you have an OpenAPI v3 declaration, zimic-http typegen can automatically generate the types of your schema.
• 📌 Type-safe native APIs: Declare type-safe Headers, URLSearchParams, and FormData objects, fully compatible with their native counterparts.

Getting started

Check our getting started guide.

Installation

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

Basic usage

1. Declare your schema:

   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: {
           headers: { authorization: string };
           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 };
         };
       };
     };
   }>;

2. Use the types in your code!

   • Example 1: Reference the types in your code:

     import { HttpHeaders, HttpSearchParams, HttpFormData } from '@zimic/http';
     
     type UserListHeaders = Schema['/users']['GET']['request']['headers'];
     
     const headers = new HttpHeaders<UserListHeaders>({
       authorization: 'Bearer token',
     });
     
     type UserListSearchParams = Schema['/users']['GET']['request']['searchParams'];
     
     const searchParams = new HttpSearchParams<UserListSearchParams>({
       query: 'u',
       limit: '10',
     });
     
     type UserCreateBody = Schema['/users']['POST']['request']['body'];
     
     const formData = new HttpFormData<UserCreateBody>();
     formData.append('username', 'user');

   • Example 2: Using @zimic/fetch:

     import { createFetch } from '@zimic/fetch';
     
     const fetch = createFetch<Schema>({
       baseURL: 'http://localhost:3000',
     });
     
     const response = await fetch('/users', {
       method: 'POST',
       body: { username: 'user' },
     });
     
     if (!response.ok) {
       throw response.error;
     }
     
     console.log(await response.json()); // { username: 'user' }

   • Example 3: Using @zimic/interceptor:

     import { httpInterceptor } from '@zimic/interceptor/http';
     
     const interceptor = httpInterceptor.create<Schema>({
       type: 'local',
       baseURL: 'http://localhost:3000',
     });
     
     await interceptor.start();
     
     interceptor.post('/users').respond({
       status: 201,
       body: { username: body.username },
     });

Documentation

• Getting started
• API reference
• CLI reference
  • zimic-http typegen

Examples

Visit our examples to see how to use Zimic with popular frameworks, libraries, and use cases.

Changelog

The changelog is available on our GitHub Releases page.

Contributing

Interested in contributing to Zimic? Check out our contributing guide to get started!