docs: update README for v2

mashabow · mashabow · commit b72d950b35d1 · 2024-08-31T01:29:05.000+09:00
diff --git a/README.ja.md b/README.ja.md
@@ -2,9 +2,9 @@
 
 MSW を型安全に使うための、aspida ユーザー向けのラッパー
 
-- Simple.
-- Type safe.
-- Aspida-like interface.
+- Simple
+- Type safe
+- Aspida-like interface
 
 [English](./README.md) / [日本語](./README.ja.md)
 
@@ -17,52 +17,62 @@ npm install mswpida --save-dev
 ## 使い方
 
 ```ts
-import { createTypedRest } from 'mswpida';
+// 1. aspida で生成した `api` 関数から `typedHttp` を作る
+
+import { createTypedHttp } from 'mswpida';
 import api from './awesome/store/$api';
 
-// 1. aspida で生成した `api` 関数から `typedRest` を作る
-const typedRest = createTypedRest(api);
+const typedHttp = createTypedHttp(api);
+
+// 2. `typedHttp` を使って MSW の request handler を書く
+
+import { HttpResponse } from 'msw';
 
-// 2. `typedRest` を使って MSW の request handler を書く
 const handlers = [
-  typedRest.products._productId.images.$post((req, res, ctx) => {
-    console.log(`Add an image to product ${req.params.productId}`); // パスパラメータに型がついている ✅
-    console.log(`Image description: ${req.body.description}`); // リクエストボディに型がついている ✅
-    return res(
-      ctx.status(201),
-      ctx.json({ id: 123, ...req.body }), // レスポンスボディにも型がついている ✅
+  typedHttp.products._productId.images.$post(({ request, params }) => {
+    console.log(`Add an image to product ${params.productId}`); // パスパラメータに型がついている ✅
+
+    const reqBody = await request.json();
+    console.log(`Image description: ${reqBody.description}`); // リクエストボディに型がついている ✅
+
+    return HttpResponse.json(
+      { id: 123, ...reqBody }, // レスポンスボディにも型がついている ✅
+      { status: 201 },
     );
   }),
   // ...
 ];
 
 // 3. 以降は通常の MSW の使い方と同様
-import { setupWorker } from 'msw'; // or `setupServer`
+
+import { setupWorker } from 'msw/browser';
+// or
+// import { setupServer } from 'msw/node';
 
 await setupWorker(...handlers).start();
 ```
 
-### `createTypedRest(api, options?)`
+### `createTypedHttp(api, options?)`
 
-aspida で生成した `api` 関数を元にして、`typedRest` というオブジェクトを作成します。この `typedRest` は、MSW の [request handler](https://v1.mswjs.io/docs/basics/request-handler) を書くためのラッパーです。
+aspida で生成した `api` 関数を元にして、`typedHttp` というオブジェクトを作成します。この `typedHttp` は、MSW の [request handler](https://mswjs.io/docs/concepts/request-handler) を書くためのラッパーです。
 
 #### オプション
 
 - `baseURL` (optional): API のベース URL を指定します。aspida の `baseURL` オプションと同様です。
 
 ```ts
-createTypedRest(api, { baseURL: 'https://staging.example.com' });
+createTypedHttp(api, { baseURL: 'https://staging.example.com' });
 ```
 
-### `typedRest`
+### `typedHttp`
 
-MSW の [request handler](https://v1.mswjs.io/docs/basics/request-handler) を書くためのオブジェクトで、実態としては MSW の [`rest`](https://v1.mswjs.io/docs/api/rest) の薄いラッパーです。[`rest`](https://v1.mswjs.io/docs/api/rest) とほぼ同じ使い方ですが、パスやメソッドは aspida のような形式で表現します。
+MSW の [request handler](https://mswjs.io/docs/concepts/request-handler) を書くためのオブジェクトで、実態としては MSW の [`http`](https://mswjs.io/docs/api/http) の薄いラッパーです。使い方は `http` とほぼ同じですが、パスやメソッドは aspida のような形式で表現します。
 
 ```ts
-const handler = typedRest.products._productId.images.$post((req, res, ctx) => ...);
+const handler = typedHttp.products._productId.images.$post(({ request, params }) => ...);
 
 // これは以下と同等
-const handler = rest.post('https://example.com/products/:productId/images', (req, res, ctx) => ...);
+const handler = http.post('https://example.com/products/:productId/images', ({ request, params }) => ...);
 ```
 
 #### パス
@@ -72,36 +82,36 @@ const handler = rest.post('https://example.com/products/:productId/images', (req
 `.$path()` を使うと、そのエンドポイントのパスを文字列として取得できます。
 
 ```ts
-const path = typedRest.products._productId.images.$path();
+const path = typedHttp.products._productId.images.$path();
 // -> 'https://example.com/products/:productId/images'
 ```
 
 #### メソッド
 
-`.$get(resolver)` や `.$post(resolver)` など、HTTP メソッドに `$` を付けた関数で表現します。引数は MSW の [response resolver](https://v1.mswjs.io/docs/basics/response-resolver) ですが、aspida の `api` から導出した具体的な型が以下の3つについているため、型注釈を書く必要はありません。
+`.$get(resolver)` や `.$post(resolver)` など、HTTP メソッドに `$` を付けた関数で表現します。引数は MSW の [response resolver](https://mswjs.io/docs/concepts/response-resolver) ですが、aspida の `api` から導出した具体的な型が以下の3つについているため、型注釈を書く必要はありません。
 
-- パスパラメータ `req.params`
+- パスパラメータ：[`params`](https://mswjs.io/docs/network-behavior/rest#reading-path-parameters)
   - MSW の仕様上、値の型は常に `string` になります。
-- リクエストボディ `req.body`
-  - ただし `await req.json()` の方には型はつかず、[常に `any` になります](https://github.com/mswjs/msw/issues/1318#issuecomment-1205149710)。
-- レスポンスボディ `res(ctx.json())`
+- リクエストボディ：[`await request.json()`](https://mswjs.io/docs/network-behavior/rest#reading-request-body)
+- レスポンスボディ：[`HttpResponse.json()`](https://mswjs.io/docs/api/http-response#httpresponsejsonbody-init) の第1引数
 
 ```ts
-const handler = typedRest.products._productId.images.$post((req, res, ctx) => {
-  console.log(`Add an image to product ${req.params.productId}`); // パスパラメータに型がついている ✅
-  console.log(`Image description: ${req.body.description}`); // リクエストボディに型がついている ✅
-  return res(
-    ctx.status(201),
-    ctx.json({ id: 123, ...req.body }), // レスポンスボディにも型がついている ✅
-  );
-});
-```
+const handler = typedHttp.products._productId.images.$post(
+  ({ request, params }) => {
+    console.log(`Add an image to product ${params.productId}`); // パスパラメータに型がついている ✅
 
-## FAQ
+    const reqBody = await request.json();
+    console.log(`Image description: ${reqBody.description}`); // リクエストボディに型がついている ✅
 
-### MSW 2.x には対応していますか？
+    return HttpResponse.json(
+      { id: 123, ...reqBody }, // レスポンスボディにも型がついている ✅
+      { status: 201 },
+    );
+  },
+);
+```
 
-まだ対応していませんが、[対応予定です](https://github.com/mashabow/mswpida/issues/13)。
+## FAQ
 
 ### エラーレスポンスなど、正常系以外のレスポンスボディを返そうとすると型エラーになります。
 
@@ -110,16 +120,24 @@ const handler = typedRest.products._productId.images.$post((req, res, ctx) => {
 ```ts
 type ErrorResponseBody = { errorCode: string };
 
-const handler = typedRest.products._productId.images.$post<ErrorResponseBody>(
-  (req, res, ctx) => {
-    if (req.params.productId === 'bad_id') {
-      return res(ctx.status(404), ctx.json({ errorCode: 'product_not_found' }));
+const handler = typedHttp.products._productId.images.$post<ErrorResponseBody>(
+  ({ request, params }) => {
+    if (params.productId === 'bad_id') {
+      return HttpResponse.json(
+        { errorCode: 'product_not_found' },
+        { status: 404 },
+      );
     }
-    return res(ctx.status(201), ctx.json({ id: 123, ...req.body }));
+    const reqBody = await request.json();
+    return HttpResponse.json({ id: 123, ...reqBody }, { status: 201 });
   },
 );
 ```
 
+### MSW v1 と一緒に使えますか？
+
+mswpida v1 を使ってください。
+
 ## ライセンス
 
 MIT
diff --git a/README.md b/README.md
@@ -2,9 +2,9 @@
 
 A wrapper to use MSW in a type-safe manner for aspida users.
 
-- Simple.
-- Type safe.
-- Aspida-like interface.
+- Simple
+- Type safe
+- Aspida-like interface
 
 [English](./README.md) / [日本語](./README.ja.md)
 
@@ -17,52 +17,62 @@ npm install mswpida --save-dev
 ## Usage
 
 ```ts
-import { createTypedRest } from 'mswpida';
+// 1. Create `typedHttp` from the `api` function generated by aspida.
+
+import { createTypedHttp } from 'mswpida';
 import api from './awesome/store/$api';
 
-// 1. Create `typedRest` from the `api` function generated by aspida.
-const typedRest = createTypedRest(api);
+const typedHttp = createTypedHttp(api);
+
+// 2. Write MSW's request handler using `typedHttp`.
+
+import { HttpResponse } from 'msw';
 
-// 2. Write MSW's request handler using `typedRest`.
 const handlers = [
-  typedRest.products._productId.images.$post((req, res, ctx) => {
-    console.log(`Add an image to product ${req.params.productId}`); // Path parameter is typed ✅
-    console.log(`Image description: ${req.body.description}`); // Request body is typed ✅
-    return res(
-      ctx.status(201),
-      ctx.json({ id: 123, ...req.body }), // Response body is also typed ✅
+  typedHttp.products._productId.images.$post(({ request, params }) => {
+    console.log(`Add an image to product ${params.productId}`); // Path parameter is typed ✅
+
+    const reqBody = await request.json();
+    console.log(`Image description: ${reqBody.description}`); // Request body is typed ✅
+
+    return HttpResponse.json(
+      { id: 123, ...reqBody }, // Response body is also typed ✅
+      { status: 201 },
     );
   }),
   // ...
 ];
 
 // 3. Subsequent usage is the same as the regular MSW usage.
-import { setupWorker } from 'msw'; // or `setupServer`
+
+import { setupWorker } from 'msw/browser';
+// or
+// import { setupServer } from 'msw/node';
 
 await setupWorker(...handlers).start();
 ```
 
-### `createTypedRest(api, options?)`
+### `createTypedHttp(api, options?)`
 
-Creates a `typedRest` object based on the `api` function generated by aspida. This `typedRest` is a wrapper to write MSW's [request handler](https://v1.mswjs.io/docs/basics/request-handler).
+Creates a `typedHttp` object based on the `api` function generated by aspida. This `typedHttp` is a wrapper to write MSW's [request handler](https://mswjs.io/docs/concepts/request-handler).
 
 #### Options
 
 - `baseURL` (optional): Specifies the base URL for the API. Works the same as aspida's `baseURL` option.
 
 ```ts
-createTypedRest(api, { baseURL: 'https://staging.example.com' });
+createTypedHttp(api, { baseURL: 'https://staging.example.com' });
 ```
 
-### `typedRest`
+### `typedHttp`
 
-An object for writing MSW's [request handler](https://v1.mswjs.io/docs/basics/request-handler). Essentially, it is a thin wrapper for MSW's [`rest`](https://v1.mswjs.io/docs/api/rest). The usage is almost identical to [`rest`](https://v1.mswjs.io/docs/api/rest), but paths and methods are expressed in an aspida-like format.
+An object for writing MSW's [request handler](https://mswjs.io/docs/concepts/request-handler). Essentially, it is a thin wrapper for MSW's [`http`](https://mswjs.io/docs/api/http). The usage is almost identical to `http`, but paths and methods are expressed in an aspida-like format.
 
 ```ts
-const handler = typedRest.products._productId.images.$post((req, res, ctx) => ...);
+const handler = typedHttp.products._productId.images.$post(({ request, params }) => ...);
 
 // This is equivalent to:
-const handler = rest.post('https://example.com/products/:productId/images', (req, res, ctx) => ...);
+const handler = http.post('https://example.com/products/:productId/images', ({ request, params }) => ...);
 ```
 
 #### Path
@@ -72,36 +82,36 @@ Paths are expressed as properties. While path parameters are expressed with func
 Use `.$path()` to get the path of that endpoint as a string.
 
 ```ts
-const path = typedRest.products._productId.images.$path();
+const path = typedHttp.products._productId.images.$path();
 // -> 'https://example.com/products/:productId/images'
 ```
 
 #### Method
 
-Expressed as the `$`-prefixed HTTP method function, like `.$get(resolver)` or `.$post(resolver)`. The argument is MSW's [response resolver](https://v1.mswjs.io/docs/basics/response-resolver). The following three are typed from aspida's `api`, so no type annotations are required:
+Expressed as the `$`-prefixed HTTP method function, like `.$get(resolver)` or `.$post(resolver)`. The argument is MSW's [response resolver](https://mswjs.io/docs/concepts/response-resolver). The following three are typed from aspida's `api`, so no type annotations are required:
 
-- Path parameters `req.params`
+- Path parameters: [`params`](https://mswjs.io/docs/network-behavior/rest#reading-path-parameters)
   - As per MSW's behavior, the type of value is always `string`.
-- Request body `req.body`
-  - Note that for `await req.json()`, [the type is always `any`](https://github.com/mswjs/msw/issues/1318#issuecomment-1205149710).
-- Response body `res(ctx.json())`
+- Request body: [`await request.json()`](https://mswjs.io/docs/network-behavior/rest#reading-request-body)
+- Response body: the first argument of [`HttpResponse.json()`](https://mswjs.io/docs/api/http-response#httpresponsejsonbody-init)
 
 ```ts
-const handler = typedRest.products._productId.images.$post((req, res, ctx) => {
-  console.log(`Add an image to product ${req.params.productId}`); // Path parameter is typed ✅
-  console.log(`Image description: ${req.body.description}`); // Request body is typed ✅
-  return res(
-    ctx.status(201),
-    ctx.json({ id: 123, ...req.body }), // Response body is also typed ✅
-  );
-});
-```
+const handler = typedHttp.products._productId.images.$post(
+  ({ request, params }) => {
+    console.log(`Add an image to product ${params.productId}`); // Path parameter is typed ✅
 
-## FAQ
+    const reqBody = await request.json();
+    console.log(`Image description: ${reqBody.description}`); // Request body is typed ✅
 
-### Is it compatible with MSW 2.x?
+    return HttpResponse.json(
+      { id: 123, ...reqBody }, // Response body is also typed ✅
+      { status: 201 },
+    );
+  },
+);
+```
 
-Not yet, but [it's planned](https://github.com/mashabow/mswpida/issues/13).
+## FAQ
 
 ### How can I return an error response without getting a type error?
 
@@ -110,16 +120,24 @@ By using method with a type parameter like `.$get<T>()` or `.$post<T>()`, you ca
 ```ts
 type ErrorResponseBody = { errorCode: string };
 
-const handler = typedRest.products._productId.images.$post<ErrorResponseBody>(
-  (req, res, ctx) => {
-    if (req.params.productId === 'bad_id') {
-      return res(ctx.status(404), ctx.json({ errorCode: 'product_not_found' }));
+const handler = typedHttp.products._productId.images.$post<ErrorResponseBody>(
+  ({ request, params }) => {
+    if (params.productId === 'bad_id') {
+      return HttpResponse.json(
+        { errorCode: 'product_not_found' },
+        { status: 404 },
+      );
     }
-    return res(ctx.status(201), ctx.json({ id: 123, ...req.body }));
+    const reqBody = await request.json();
+    return HttpResponse.json({ id: 123, ...reqBody }, { status: 201 });
   },
 );
 ```
 
+### Can I use it with MSW v1?
+
+Please use mswpida v1 for MSW v1.
+
 ## License
 
 MIT
