@zimic/fetch 0.1.0-canary.9 → 0.1.1-canary.1

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/fetch
 </h1>
 
 <p align="center">
-  TypeScript-first HTTP request mocking
+  TypeScript-first fetch-like API client
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/zimic">npm</a>
+  <a href="https://www.npmjs.com/package/@zimic/fetch">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,157 @@
 
 [![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/fetch](https://img.shields.io/npm/dm/@zimic/fetch?style=flat&logo=npm&color=0E69BE&label=%20%40zimic%2Ffetch&labelColor=353C43)](https://www.npmjs.com/package/@zimic/fetch)&nbsp;
+[![Bundle size - @zimic/fetch](https://badgen.net/bundlephobia/minzip/@zimic/fetch?color=0E69BE&labelColor=353C43&label=@zimic/fetch%20min%20gzip)](https://bundlephobia.com/package/@zimic/fetch)<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/fetch` is a minimal (1 kB minified and gzipped), zero-dependency, and type-safe `fetch`-like API client.
+
+> [!WARNING]
+>
+> :construction: This library is **experimental**.
 
 ## 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}`;
+- :sparkles: **Type-safe `fetch`**: Create a type-safe
+  [`fetch`-like](https://developer.mozilla.org/docs/Web/API/Fetch_API) API client. Use your
+  [`@zimic/http` schema](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http‐schemas) and have your requests and
+  responses fully typed by default.
+- :muscle: **Developer experience**: `@zimic/fetch` seeks to be as compatible with the
+  [native Fetch API](https://developer.mozilla.org/docs/Web/API/Fetch_API) as possible, while providing an ergonomic
+  interface to improve type safety. Define default options to apply to your requests, such as a base URL, headers,
+  search parameters, and more. Inspect and modify requests and responses using
+  [`onRequest`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchonrequest) and
+  [`onResponse`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#fetchonresponse) listeners.
+
+## Getting started
+
+Check our [getting started guide](https://github.com/zimicjs/zimic/wiki/getting‐started‐fetch).
+
+### Installation
+
+| Manager | Command                                       |
+| :-----: | --------------------------------------------- |
+|   npm   | `npm install @zimic/http @zimic/fetch --save` |
+|  yarn   | `yarn add @zimic/http @zimic/fetch`           |
+|  pnpm   | `pnpm add @zimic/http @zimic/fetch`           |
+
+## Basic usage
+
+1.  Declare your HTTP schema using [`@zimic/http`](https://github.com/zimicjs/zimic/wiki/api‐zimic‐http):
+
+    ```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 };
+            500: { body: RequestError };
+          };
+        };
+
+        GET: {
+          request: {
+            searchParams: {
+              query?: string;
+              limit?: `${number}`;
+            };
+          };
+          response: {
+            200: { body: User[] };
+            404: { body: RequestError };
+            500: { body: RequestError };
+          };
         };
       };
-      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 };
+
+      '/users/:userId': {
+        PATCH: {
+          request: {
+            headers: { authorization: string };
+            body: Partial<User>;
+          };
+          response: {
+            204: {};
+            400: { body: RequestError };
+            500: { 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);
-});
-```
+    }>;
+    ```
+
+2.  Create your [fetch client](https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch#createfetch):
+
+    ```ts
+    import { createFetch } from '@zimic/fetch';
+
+    const fetch = createFetch<Schema>({
+      baseURL: 'http://localhost:3000',
+    });
+    ```
+
+3.  Enjoy requests and responses typed by default!
+
+    ```ts
+    const response = await fetch('/users', {
+      method: 'GET',
+      searchParams: { query: 'u', limit: '10' },
+    });
+
+    if (response.status === 404) {
+      return null; // Not found
+    }
+
+    if (!response.ok) {
+      throw response.error;
+    }
+
+    const users = await response.json();
+    return users; // User[]
+    ```
 
 ## Documentation
 
 - [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)
-
-> [!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.
+- [Getting started](https://github.com/zimicjs/zimic/wiki/getting‐started‐fetch)
+- [API reference](https://github.com/zimicjs/zimic/wiki/api‐zimic‐fetch)
 
 ## 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