@zimic/http 0.1.0-canary.7 → 0.1.1-canary.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Diego Aquino
+Copyright (c) 2023-Present Zimic Team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 documentation files (the "Software"), to deal in the Software without restriction, including without limitation the

package/README.md

@@ -3,15 +3,15 @@
 </p>
 
 <h1 align="center">
-  Zimic
+  @zimic/http
 </h1>
 
 <p align="center">
-  TypeScript-first HTTP request mocking
+  TypeScript-first HTTP intercepting and mocking
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/zimic">npm</a>
+  <a href="https://www.npmjs.com/package/@zimic/http">npm</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://github.com/zimicjs/zimic/wiki">Docs</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
@@ -26,196 +26,190 @@
 
 [![CI](https://github.com/zimicjs/zimic/actions/workflows/ci.yaml/badge.svg?branch=canary)](https://github.com/zimicjs/zimic/actions/workflows/ci.yaml)&nbsp;
 [![Coverage](https://img.shields.io/badge/Coverage-100%25-31C654?labelColor=353C43)](https://github.com/zimicjs/zimic/actions)&nbsp;
-[![License](https://img.shields.io/github/license/zimicjs/zimic?color=0E69BE&label=License&labelColor=353C43)](https://github.com/zimicjs/zimic/blob/canary/LICENSE.md)
-[![NPM Downloads](https://img.shields.io/npm/dm/zimic?style=flat&logo=npm&color=0E69BE&label=Downloads&labelColor=353C43)](https://www.npmjs.com/package/zimic)&nbsp;
-[![Stars](https://img.shields.io/github/stars/zimicjs/zimic)](https://github.com/zimicjs/zimic)&nbsp;
+[![License](https://img.shields.io/github/license/zimicjs/zimic?color=0E69BE&label=License&labelColor=353C43)](https://github.com/zimicjs/zimic/blob/canary/LICENSE.md)&nbsp;
+[![Stars](https://img.shields.io/github/stars/zimicjs/zimic)](https://github.com/zimicjs/zimic)
+
+[![NPM Downloads - @zimic/http](https://img.shields.io/npm/dm/@zimic/http?style=flat&logo=npm&color=0E69BE&label=%20%40zimic%2Fhttp&labelColor=353C43)](https://www.npmjs.com/package/@zimic/http)&nbsp;
+[![Bundle size - @zimic/http](https://badgen.net/bundlephobia/minzip/@zimic/http?color=0E69BE&labelColor=353C43&label=@zimic/http%20min%20gzip)](https://bundlephobia.com/package/@zimic/http)<br />
 
 </div>
 
 ---
 
-Zimic is a lightweight, thoroughly tested, TypeScript-first HTTP request mocking library, inspired by
-[Zod](https://github.com/colinhacks/zod)'s type inference and using [MSW](https://github.com/mswjs/msw) under the hood.
+- [Features](#features)
+- [Getting started](#getting-started)
+  - [Installation](#installation)
+- [Basic usage](#basic-usage)
+- [Documentation](#documentation)
+- [Examples](#examples)
+- [Changelog](#changelog)
+- [Contributing](#contributing)
+
+---
+
+`@zimic/http` is a collection of type-safe utilities to handle HTTP requests and responses, including headers, search
+params, and form data.
+
+> [!NOTE]
+>
+> :seedling: This library is in **beta**.
 
 ## Features
 
-Zimic provides a flexible and type-safe way to mock HTTP requests.
-
-- :zap: **Statically-typed mocks**: Declare the
-  [schema](https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http‐schemas) of your HTTP endpoints and create
-  fully typed mocks. If you have an [OpenAPI v3](https://swagger.io/specification) schema, use
-  [`zimic-http typegen`](https://github.com/zimicjs/zimic/wiki/cli‐zimic‐typegen) to automatically generate types and
-  keep your mocks in sync with your API.
-- :link: **Network-level intercepts**: Internally, Zimic combines [MSW](https://github.com/mswjs/msw) and
-  [interceptor servers](https://github.com/zimicjs/zimic/wiki/cli‐zimic‐server) to act on real HTTP requests. From you
-  application's point of view, the mocked responses are indistinguishable from the real ones.
-- :wrench: **Flexibility**: Mock external services and reliably test how your application behaves. Simulate success,
-  loading, and error states with ease using [standard web APIs](https://developer.mozilla.org/docs/Web/API).
-- :bulb: **Simplicity**: Zimic was designed to encourage clarity, simplicity, and robustness in your mocks. Check our
-  [getting started guide](https://github.com/zimicjs/zimic/wiki/getting‐started) and starting mocking!
-
-```ts
-import { type HttpSchema } from '@zimic/http';
-import { httpInterceptor } from '@zimic/interceptor/http';
-
-// 1. Declare your types:
-interface User {
-  username: string;
-}
-
-interface RequestError {
-  code: string;
-  message: string;
-}
-
-// 2. Declare your HTTP schema:
-// https://bit.ly/zimic-interceptor-http-schemas
-type MySchema = HttpSchema<{
-  '/users': {
-    POST: {
-      request: { body: User };
-      response: {
-        201: { body: User };
-        400: { body: RequestError };
-        409: { body: RequestError };
-      };
-    };
-
-    GET: {
-      request: {
-        headers: { authorization: string };
-        searchParams: {
-          username?: 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 };
-      };
-    };
-  };
-}>;
-
-// 3. Create your interceptor:
-// https://bit.ly/zimic-interceptor-http#httpinterceptorcreateoptions
-const myInterceptor = httpInterceptor.create<MySchema>({
-  type: 'local',
-  baseURL: 'http://localhost:3000',
-  saveRequests: true, // Allow access to `handler.requests()`
-});
-
-// 4. Manage your interceptor lifecycle:
-// https://bit.ly/zimic-guides-testing
-beforeAll(async () => {
-  // 4.1. Start intercepting requests:
-  // https://bit.ly/zimic-interceptor-http#http-interceptorstart
-  await myInterceptor.start();
-});
-
-beforeEach(() => {
-  // 4.2. Clear interceptors so that no tests affect each other:
-  // https://bit.ly/zimic-interceptor-http#http-interceptorclear
-  myInterceptor.clear();
-});
-
-afterEach(() => {
-  // 4.3. Check that all expected requests were made:
-  // https://bit.ly/zimic-interceptor-http#http-interceptorchecktimes
-  myInterceptor.checkTimes();
-});
-
-afterAll(async () => {
-  // 4.4. Stop intercepting requests:
-  // https://bit.ly/zimic-interceptor-http#http-interceptorstop
-  await myInterceptor.stop();
-});
-
-// Enjoy mocking!
-test('example', async () => {
-  const users: User[] = [{ username: 'my-user' }];
-
-  // 5. Declare your mocks:
-  // https://bit.ly/zimic-interceptor-http#http-interceptormethodpath
-  const myHandler = myInterceptor
-    .get('/users')
-    // 5.1. Use restrictions to make declarative assertions and narrow down your mocks:
-    // https://bit.ly/zimic-interceptor-http#http-handlerwithrestriction
-    .with({
-      headers: { authorization: 'Bearer my-token' },
-      searchParams: { username: 'my' },
-    })
-    // 5.2. Respond with your mock data:
-    // https://bit.ly/zimic-interceptor-http#http-handlerresponddeclaration
-    .respond({
-      status: 200,
-      body: users,
-    })
-    // 5.3. Define how many requests you expect your application to make:
-    // https://bit.ly/zimic-interceptor-http#http-handlertimes
-    .times(1);
-
-  // 6. Run your application and make requests:
-  // ...
-
-  // 7. Check the requests you expect:
-  // https://bit.ly/zimic-interceptor-http#http-handlerrequests
-  //
-  // NOTE: The code below checks the requests manually. This is optional in this
-  // example because the `with` and `times` calls act as a declarative validation,
-  // meaning that exactly one request is expected with specific data. If fewer or
-  // more requests are received, the test will fail when `myInterceptor.checkTimes()`
-  // is called in the `afterEach` hook.
-  const requests = myHandler.requests();
-  expect(requests).toHaveLength(1);
-
-  expect(requests[0].headers.get('authorization')).toBe('Bearer my-token');
-
-  expect(requests[0].searchParams.size).toBe(1);
-  expect(requests[0].searchParams.get('username')).toBe('my');
-
-  expect(requests[0].body).toBe(null);
-});
-```
+- :star: **HTTP schemas and typegen**: Declare the structure of your HTTP endpoints as a TypeScript
+  [schema](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas) and use it to type your HTTP requests and
+  responses. If you have an [OpenAPI v3](https://swagger.io/specification) declaration,
+  [`zimic-http typegen`](https://github.com/zimicjs/zimic/wiki/cli‐zimic‐typegen) can automatically generate the types
+  of your schema.
+- :pushpin: **Type-safe native APIs**: Declare type-safe
+  [`Headers`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http#httpheaders),
+  [`URLSearchParams`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http#httpsearchparams), and
+  [`FormData`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http#httpformdata) objects, fully compatible with their
+  native counterparts.
+
+## Getting started
+
+Check our [getting started guide](https://github.com/zimicjs/zimic/wiki/getting‐started‐http).
+
+### 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](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas):
+
+   ```ts
+   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:
+
+     ```ts
+     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`](../zimic-fetch):
+
+     ```ts
+     import { createFetch } from '@zimic/fetch';
 
-## Documentation
+     const fetch = createFetch<Schema>({
+       baseURL: 'http://localhost:3000',
+     });
 
-- [Introduction](https://github.com/zimicjs/zimic/wiki)
-- [Getting started](https://github.com/zimicjs/zimic/wiki/getting‐started)
-- [API reference](https://github.com/zimicjs/zimic/wiki/api‐zimic)
-- [CLI reference](https://github.com/zimicjs/zimic/wiki/cli‐zimic)
-- Guides
-  - [Testing](https://github.com/zimicjs/zimic/wiki/guides‐testing)
+     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`](../zimic-interceptor):
+
+     ```ts
+     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 },
+     });
+     ```
 
-> [!NOTE]
->
-> Zimic has gone a long way in v0, but we're not yet v1!
->
-> Reviews and improvements to the public API are possible, so breaking changes may **_exceptionally_** land without a
-> major release during v0. Despite of that, we do not expect big mental model shifts. Usually, migrating to a new Zimic
-> release requires minimal to no refactoring. During v0, we will follow these guidelines:
->
-> - Breaking changes, if any, will be delivered in the next **_minor_** version.
-> - Breaking changes, if any, will be documented in the [version release](https://github.com/zimicjs/zimic/releases),
->   along with a migration guide detailing the introduced changes and suggesting steps to migrate.
+## Documentation
+
+- [Getting started](https://github.com/zimicjs/zimic/wiki/getting‐started‐http)
+- [API reference](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http)
+- CLI reference
+  - [`zimic-http typegen`](https://github.com/zimicjs/zimic/wiki/cli‐zimic‐typegen)
 
 ## Examples
 
-Visit our [examples](../../examples/README.md) to see how to use Zimic with popular frameworks, libraries, and use cases!
+Visit our [examples](../../examples/README.md) to see how to use Zimic with popular frameworks, libraries, and use
+cases.
 
 ## Changelog