msw-fetch-mock 0.3.3 → 0.4.0

package/docs/cloudflare-migration.zh-TW.md

@@ -0,0 +1,80 @@
+# Cloudflare Workers 遷移指南
+
+如果你正在將測試從 Cloudflare Workers 的 `cloudflare:test` 遷移到標準的 Node.js 測試環境，`msw-fetch-mock` 提供了你已經熟悉的相同 `fetchMock` API。
+
+## API 對照
+
+| cloudflare:test                                    | msw-fetch-mock                                              |
+| -------------------------------------------------- | ----------------------------------------------------------- |
+| `import { fetchMock } from 'cloudflare:test'`      | `import { fetchMock } from 'msw-fetch-mock'`                |
+| `fetchMock.activate()`                             | `await fetchMock.activate()`                                |
+| `fetchMock.disableNetConnect()`                    | `fetchMock.disableNetConnect()`                             |
+| `fetchMock.enableNetConnect(matcher?)`             | `fetchMock.enableNetConnect(matcher?)`                      |
+| `fetchMock.deactivate()`                           | `fetchMock.deactivate()`                                    |
+| `fetchMock.get(origin).intercept(opts).reply(...)` | `fetchMock.get(origin).intercept(opts).reply(...)`          |
+| `.replyWithError(error)`                           | `.replyWithError(error)`                                    |
+| `.reply(...).delay(ms)`                            | `.reply(...).delay(ms)`                                     |
+| `fetchMock.getCallHistory()`                       | `fetchMock.getCallHistory()` 或 `fetchMock.calls`           |
+| `fetchMock.clearCallHistory()`                     | `fetchMock.clearCallHistory()` 或 `fetchMock.calls.clear()` |
+| `fetchMock.assertNoPendingInterceptors()`          | `fetchMock.assertNoPendingInterceptors()`                   |
+
+## 遷移前（cloudflare:test）
+
+```typescript
+import { fetchMock } from 'cloudflare:test';
+
+beforeEach(() => {
+  fetchMock.activate();
+  fetchMock.disableNetConnect();
+});
+
+afterEach(() => fetchMock.assertNoPendingInterceptors());
+
+it('呼叫 API', async () => {
+  fetchMock
+    .get('https://api.example.com')
+    .intercept({ path: '/data', method: 'GET' })
+    .reply(200, { result: 'ok' });
+
+  const res = await fetch('https://api.example.com/data');
+  expect(await res.json()).toEqual({ result: 'ok' });
+});
+```
+
+## 遷移後（msw-fetch-mock）
+
+```typescript
+import { fetchMock } from 'msw-fetch-mock';
+
+beforeAll(async () => {
+  await fetchMock.activate();
+});
+afterAll(() => fetchMock.deactivate());
+afterEach(() => {
+  fetchMock.assertNoPendingInterceptors();
+  fetchMock.reset();
+});
+
+it('呼叫 API', async () => {
+  fetchMock
+    .get('https://api.example.com')
+    .intercept({ path: '/data', method: 'GET' })
+    .reply(200, { result: 'ok' });
+
+  const res = await fetch('https://api.example.com/data');
+  expect(await res.json()).toEqual({ result: 'ok' });
+});
+```
+
+## 主要差異
+
+| 面向            | cloudflare:test                               | msw-fetch-mock                                    |
+| --------------- | --------------------------------------------- | ------------------------------------------------- |
+| 匯入            | `import { fetchMock } from 'cloudflare:test'` | `import { fetchMock } from 'msw-fetch-mock'`      |
+| Server 生命週期 | 隱式（由測試框架管理）                        | 顯式（`activate()` / `deactivate()`）             |
+| 呼叫歷史存取    | `fetchMock.getCallHistory()`                  | `fetchMock.getCallHistory()` 或 `fetchMock.calls` |
+| 呼叫歷史清理    | 每次測試自動清理                              | 在 `afterEach` 中呼叫 `reset()`                   |
+| 未處理的請求    | 必須呼叫 `disableNetConnect()`                | 預設 `onUnhandledRequest: 'error'`（直接拒絕）    |
+| 執行環境        | Cloudflare Workers (workerd)                  | Node.js                                           |
+
+> **注意：** `getCallHistory()` 和 `clearCallHistory()` 是為了 Cloudflare 相容性而提供的別名。你可以使用 Cloudflare 風格的方法或 `fetchMock.calls` getter — 兩者是等價的。

package/docs/msw-v1-legacy.zh-TW.md

@@ -0,0 +1,94 @@
+# MSW v1 Legacy 指南
+
+如果你正在使用 MSW v1（`msw@^1.x`），請使用 `msw-fetch-mock/legacy` 子路徑匯出。API 與 v2 版本相同 — 只有設定方式不同。
+
+## 安裝
+
+```bash
+npm install -D msw-fetch-mock msw@^1
+```
+
+## 設定
+
+```typescript
+import { rest } from 'msw';
+import { setupServer } from 'msw/node';
+import { createFetchMock } from 'msw-fetch-mock/legacy';
+
+const server = setupServer();
+const fetchMock = createFetchMock(rest, server);
+
+beforeAll(() => fetchMock.activate());
+afterAll(() => fetchMock.deactivate());
+afterEach(() => {
+  fetchMock.assertNoPendingInterceptors();
+  fetchMock.reset();
+});
+
+it('模擬 GET 請求', async () => {
+  fetchMock
+    .get('https://api.example.com')
+    .intercept({ path: '/users', method: 'GET' })
+    .reply(200, { users: [{ id: '1', name: 'Alice' }] });
+
+  const res = await fetch('https://api.example.com/users');
+  const data = await res.json();
+
+  expect(data.users).toHaveLength(1);
+});
+```
+
+## API 對照
+
+| MSW v2（`msw-fetch-mock`）                   | MSW v1（`msw-fetch-mock/legacy`）              |
+| -------------------------------------------- | ---------------------------------------------- |
+| `import { fetchMock } from 'msw-fetch-mock'` | 無單例 — 必須使用 `createFetchMock`            |
+| `import { createFetchMock } from '.../node'` | `import { createFetchMock } from '.../legacy'` |
+| `createFetchMock(server?)`                   | `createFetchMock(rest, server?)`               |
+| `import { http } from 'msw'`                 | `import { rest } from 'msw'`                   |
+
+## 主要差異
+
+| 面向             | MSW v2                                    | MSW v1（Legacy）                  |
+| ---------------- | ----------------------------------------- | --------------------------------- |
+| 匯入             | `msw-fetch-mock` 或 `msw-fetch-mock/node` | `msw-fetch-mock/legacy`           |
+| 工廠函式         | `createFetchMock(server?)`                | `createFetchMock(rest, server?)`  |
+| 單例             | `fetchMock` 預建實例                      | 不提供 — 使用 `createFetchMock`   |
+| Handler 內部實作 | 使用 `http.*` + `HttpResponse`            | 使用 `rest.*` + `(req, res, ctx)` |
+| MSW 版本         | `msw@^2.12.7`                             | `msw@^1.0.0`                      |
+
+## 匯出項目
+
+`msw-fetch-mock/legacy` 子路徑匯出：
+
+| 匯出                             | 類型 | 說明                                |
+| -------------------------------- | ---- | ----------------------------------- |
+| `createFetchMock(rest, server?)` | 函式 | 建立適用於 MSW v1 的 FetchMock 實例 |
+| `FetchMock`                      | 類別 | 核心模擬類別（與 v2 相同）          |
+| `createLegacyHandlerFactory`     | 函式 | 低階：建立 v1 相容的 handler 工廠   |
+| `LegacyRestApi`                  | 型別 | MSW v1 的 `rest` 物件型別           |
+
+## 從 MSW v1 遷移到 v2
+
+當你將 MSW 從 v1 升級到 v2 時，更新你的匯入：
+
+```diff
+- import { rest } from 'msw';
+- import { createFetchMock } from 'msw-fetch-mock/legacy';
+- const fetchMock = createFetchMock(rest, server);
++ import { createFetchMock } from 'msw-fetch-mock/node';
++ const fetchMock = createFetchMock(server);
+```
+
+或使用單例進行獨立模式：
+
+```diff
+- import { rest } from 'msw';
+- import { setupServer } from 'msw/node';
+- import { createFetchMock } from 'msw-fetch-mock/legacy';
+- const server = setupServer();
+- const fetchMock = createFetchMock(rest, server);
++ import { fetchMock } from 'msw-fetch-mock';
+```
+
+其餘 API（`get()`、`intercept()`、`reply()`、`calls` 等）維持不變。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msw-fetch-mock",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Undici-style fetch mock API built on MSW (Mock Service Worker)",
   "type": "module",
   "license": "MIT",
@@ -57,6 +57,15 @@
       },
       "import": "./dist/legacy.js",
       "require": "./dist/legacy.cjs"
+    },
+    "./native": {
+      "source": "./src/native.ts",
+      "types": {
+        "import": "./dist/native.d.ts",
+        "require": "./dist/native.d.cts"
+      },
+      "import": "./dist/native.js",
+      "require": "./dist/native.cjs"
     }
   },
   "files": [
@@ -81,6 +90,11 @@
   "peerDependencies": {
     "msw": "^1.0.0 || ^2.12.7"
   },
+  "peerDependenciesMeta": {
+    "msw": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "eslint": "^9.39.2",