msw-fetch-mock 0.1.1 → 0.2.0

package/README.md

@@ -18,14 +18,12 @@ npm install -D msw-fetch-mock msw
 
 ## Quick Start
 
-```typescript
-import { setupServer } from 'msw/node';
-import { FetchMock } from 'msw-fetch-mock';
+### Standalone (Cloudflare migration)
 
-const server = setupServer();
-const fetchMock = new FetchMock(server);
+```typescript
+import { fetchMock } from 'msw-fetch-mock';
 
-beforeAll(() => fetchMock.activate());
+beforeAll(() => fetchMock.activate({ onUnhandledRequest: 'error' }));
 afterAll(() => fetchMock.deactivate());
 afterEach(() => fetchMock.assertNoPendingInterceptors());
 
@@ -42,11 +40,63 @@ it('mocks a GET request', async () => {
 });
 ```
 
+### With an existing MSW server
+
+If you already use MSW, pass your server to share a single interceptor:
+
+```typescript
+import { setupServer } from 'msw/node';
+import { http, HttpResponse } from 'msw';
+import { FetchMock } from 'msw-fetch-mock';
+
+const server = setupServer(http.get('/api/users', () => HttpResponse.json([{ id: 1 }])));
+const fetchMock = new FetchMock(server);
+
+beforeAll(() => server.listen());
+afterAll(() => server.close());
+afterEach(() => {
+  server.resetHandlers();
+  fetchMock.assertNoPendingInterceptors();
+});
+```
+
+> **Note:** Only one MSW server can be active at a time. If another server is already listening, standalone `activate()` will throw an error guiding you to use `new FetchMock(server)` instead.
+
+## Unhandled Requests
+
+By default `activate()` uses `'error'` mode — unmatched requests cause `fetch()` to reject. This includes requests to **consumed** interceptors (once a one-shot interceptor has been used, its handler is removed from MSW).
+
+```typescript
+// Reject unmatched requests (default)
+fetchMock.activate();
+fetchMock.activate({ onUnhandledRequest: 'error' });
+
+// Log a warning but allow passthrough
+fetchMock.activate({ onUnhandledRequest: 'warn' });
+
+// Silently allow passthrough
+fetchMock.activate({ onUnhandledRequest: 'bypass' });
+
+// Custom callback
+fetchMock.activate({
+  onUnhandledRequest: (request, print) => {
+    if (request.url.includes('/health')) return; // ignore
+    print.error(); // block everything else
+  },
+});
+```
+
+> `enableNetConnect()` takes priority over `onUnhandledRequest` — allowed hosts always pass through.
+
 ## API Overview
 
+### `fetchMock` (singleton)
+
+A pre-built `FetchMock` instance for standalone use. Import and call `activate()` — no setup needed.
+
 ### `new FetchMock(server?)`
 
-Creates a `FetchMock` instance. Optionally accepts an existing MSW `SetupServer`; creates one internally if omitted.
+Creates a `FetchMock` instance. Pass an existing MSW `SetupServer` to share interceptors; omit to create one internally.
 
 ### Intercepting & Replying
 

package/dist/index.d.ts

@@ -1,5 +1,8 @@
+import { FetchMock } from './mock-server';
 export { createFetchMock, FetchMock } from './mock-server';
-export type { InterceptOptions, MockPool, MockInterceptor, MockReplyChain, ReplyOptions, PendingInterceptor, } from './mock-server';
+/** Pre-built singleton for quick standalone use (Cloudflare migration compatible). */
+export declare const fetchMock: FetchMock;
+export type { ActivateOptions, OnUnhandledRequest, InterceptOptions, MockPool, MockInterceptor, MockReplyChain, ReplyOptions, PendingInterceptor, } from './mock-server';
 export { MockCallHistory, MockCallHistoryLog } from './mock-call-history';
 export type { MockCallHistoryLogData, CallHistoryFilterCriteria } from './mock-call-history';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,cAAc,EACd,YAAY,EACZ,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE3D,sFAAsF;AACtF,eAAO,MAAM,SAAS,WAAkB,CAAC;AACzC,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,cAAc,EACd,YAAY,EACZ,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,2 +1,5 @@
+import { FetchMock } from './mock-server';
 export { createFetchMock, FetchMock } from './mock-server';
+/** Pre-built singleton for quick standalone use (Cloudflare migration compatible). */
+export const fetchMock = new FetchMock();
 export { MockCallHistory, MockCallHistoryLog } from './mock-call-history';

package/dist/mock-server.d.ts

@@ -45,18 +45,33 @@ export interface PendingInterceptor {
     timesInvoked: number;
     persist: boolean;
 }
+type PrintAPI = {
+    warning(): void;
+    error(): void;
+};
+type OnUnhandledRequestCallback = (request: Request, print: PrintAPI) => void;
+export type OnUnhandledRequest = 'bypass' | 'warn' | 'error' | OnUnhandledRequestCallback;
+export interface ActivateOptions {
+    onUnhandledRequest?: OnUnhandledRequest;
+}
 export declare class FetchMock {
     private readonly _calls;
     private server;
     private readonly ownsServer;
     private interceptors;
     private netConnectAllowed;
+    private mswHandlers;
     get calls(): MockCallHistory;
     constructor(externalServer?: SetupServerLike);
-    activate(): void;
+    activate(options?: ActivateOptions): void;
     disableNetConnect(): void;
     enableNetConnect(matcher?: string | RegExp | ((host: string) => boolean)): void;
     private isNetConnectAllowed;
+    /**
+     * Remove consumed MSW handlers so future requests to those URLs
+     * go through MSW's onUnhandledRequest instead of silently passing through.
+     */
+    private syncMswHandlers;
     getCallHistory(): MockCallHistory;
     clearCallHistory(): void;
     deactivate(): void;

package/dist/mock-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-server.d.ts","sourceRoot":"","sources":["../src/mock-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mock-server.d.ts","sourceRoot":"","sources":["../src/mock-server.ts"],"names":[],"mappings":"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"}

package/dist/mock-server.js

@@ -99,6 +99,8 @@ export class FetchMock {
     ownsServer;
     interceptors = [];
     netConnectAllowed = false;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mswHandlers = new Map();
     get calls() {
         return this._calls;
     }
@@ -106,14 +108,29 @@ export class FetchMock {
         this.server = externalServer ?? null;
         this.ownsServer = !externalServer;
     }
-    activate() {
+    activate(options) {
         if (this.ownsServer) {
+            const isPatched = Object.getOwnPropertySymbols(globalThis.fetch).some((s) => s.description === 'isPatchedModule');
+            if (isPatched) {
+                throw new Error('Another MSW server is already active. ' +
+                    'Pass your existing server to new FetchMock(server) instead.');
+            }
+            const mode = options?.onUnhandledRequest ?? 'error';
             this.server = setupServer();
             this.server.listen({
                 onUnhandledRequest: (request, print) => {
                     if (this.isNetConnectAllowed(request))
                         return;
-                    print.error();
+                    if (typeof mode === 'function') {
+                        mode(request, print);
+                    }
+                    else if (mode === 'error') {
+                        print.error();
+                    }
+                    else if (mode === 'warn') {
+                        print.warning();
+                    }
+                    // 'bypass' → do nothing
                 },
             });
         }
@@ -136,6 +153,18 @@ export class FetchMock {
             return this.netConnectAllowed.test(host);
         return this.netConnectAllowed(host);
     }
+    /**
+     * Remove consumed MSW handlers so future requests to those URLs
+     * go through MSW's onUnhandledRequest instead of silently passing through.
+     */
+    syncMswHandlers() {
+        if (!this.server || !this.ownsServer)
+            return;
+        const activeHandlers = [...this.mswHandlers.entries()]
+            .filter(([p]) => !p.consumed || p.persist)
+            .map(([, handler]) => handler);
+        this.server.resetHandlers(...activeHandlers);
+    }
     getCallHistory() {
         return this._calls;
     }
@@ -144,6 +173,7 @@ export class FetchMock {
     }
     deactivate() {
         this.interceptors = [];
+        this.mswHandlers.clear();
         this._calls.clear();
         if (this.ownsServer) {
             this.server?.close();
@@ -153,6 +183,7 @@ export class FetchMock {
     assertNoPendingInterceptors() {
         const unconsumed = this.interceptors.filter(isPending);
         this.interceptors = [];
+        this.mswHandlers.clear();
         this._calls.clear();
         if (this.ownsServer) {
             this.server?.resetHandlers();
@@ -202,6 +233,7 @@ export class FetchMock {
                     pending.timesInvoked++;
                     if (!pending.persist && pending.timesInvoked >= pending.times) {
                         pending.consumed = true;
+                        this.syncMswHandlers();
                     }
                     recordCall(this._calls, request, bodyText);
                     return bodyText;
@@ -211,6 +243,7 @@ export class FetchMock {
                     if (!this.server) {
                         throw new Error('FetchMock server is not active. Call activate() before registering interceptors.');
                     }
+                    this.mswHandlers.set(pending, handler);
                     this.server.use(handler);
                 };
                 const buildChain = (delayRef) => ({

package/docs/api.md

@@ -1,8 +1,20 @@
 # API Reference
 
+## `fetchMock` (singleton)
+
+A pre-built `FetchMock` instance for standalone use. No setup required — just import and call `activate()`.
+
+```typescript
+import { fetchMock } from 'msw-fetch-mock';
+
+beforeAll(() => fetchMock.activate({ onUnhandledRequest: 'error' }));
+afterAll(() => fetchMock.deactivate());
+afterEach(() => fetchMock.assertNoPendingInterceptors());
+```
+
 ## `new FetchMock(server?)`
 
-Creates a `FetchMock` instance.
+Creates a `FetchMock` instance. Pass an existing MSW `SetupServer` to share interceptors; omit to create one internally.
 
 ```typescript
 import { FetchMock } from 'msw-fetch-mock';
@@ -29,11 +41,46 @@ const fetchMock = new FetchMock(server);
 ### Lifecycle
 
 ```typescript
-fetchMock.activate(); // start intercepting (calls server.listen())
-fetchMock.deactivate(); // stop intercepting (calls server.close())
+fetchMock.activate(options?); // start intercepting (calls server.listen())
+fetchMock.deactivate();       // stop intercepting (calls server.close())
 ```
 
 > If you pass an external server that you manage yourself, `activate()` / `deactivate()` are no-ops.
+>
+> **Conflict detection:** In standalone mode, `activate()` checks whether `globalThis.fetch` is already patched by MSW. If so, it throws an error guiding you to pass your existing server via `new FetchMock(server)` instead.
+
+#### `ActivateOptions`
+
+| Property             | Type                 | Default   | Description                                         |
+| -------------------- | -------------------- | --------- | --------------------------------------------------- |
+| `onUnhandledRequest` | `OnUnhandledRequest` | `'error'` | How to handle requests with no matching interceptor |
+
+#### `OnUnhandledRequest`
+
+| Value                      | Behavior                                                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `'error'`                  | MSW prints an error and `fetch()` rejects with an `InternalError`                                                              |
+| `'warn'`                   | MSW prints a warning; the request passes through to the real network                                                           |
+| `'bypass'`                 | Silently passes through to the real network                                                                                    |
+| `(request, print) => void` | Custom callback. Call `print.error()` to block or `print.warning()` to warn. Return without calling either to silently bypass. |
+
+```typescript
+// Default — reject unmatched requests
+fetchMock.activate();
+fetchMock.activate({ onUnhandledRequest: 'error' });
+
+// Custom callback
+fetchMock.activate({
+  onUnhandledRequest: (request, print) => {
+    if (new URL(request.url).pathname === '/health') return;
+    print.error();
+  },
+});
+```
+
+> **Consumed interceptors:** Once a one-shot interceptor has been fully consumed, its MSW handler is removed. Subsequent requests to that URL are treated as unhandled and go through `onUnhandledRequest`. This prevents consumed interceptors from silently passing through.
+>
+> **Priority:** `enableNetConnect()` takes priority over `onUnhandledRequest` — allowed hosts always pass through regardless of the unhandled request mode.
 
 ### `fetchMock.calls`
 

package/docs/cloudflare-migration.md

@@ -6,7 +6,7 @@ If you're migrating tests from Cloudflare Workers' `cloudflare:test` to a standa
 
 | cloudflare:test                                    | msw-fetch-mock                                              |
 | -------------------------------------------------- | ----------------------------------------------------------- |
-| `import { fetchMock } from 'cloudflare:test'`      | `const fetchMock = new FetchMock(server)`                   |
+| `import { fetchMock } from 'cloudflare:test'`      | `import { fetchMock } from 'msw-fetch-mock'`                |
 | `fetchMock.activate()`                             | `fetchMock.activate()`                                      |
 | `fetchMock.disableNetConnect()`                    | `fetchMock.disableNetConnect()`                             |
 | `fetchMock.enableNetConnect(matcher?)`             | `fetchMock.enableNetConnect(matcher?)`                      |
@@ -44,11 +44,7 @@ it('calls API', async () => {
 ## After (msw-fetch-mock)
 
 ```typescript
-import { setupServer } from 'msw/node';
-import { FetchMock } from 'msw-fetch-mock';
-
-const server = setupServer();
-const fetchMock = new FetchMock(server);
+import { fetchMock } from 'msw-fetch-mock';
 
 beforeAll(() => fetchMock.activate());
 afterAll(() => fetchMock.deactivate());
@@ -67,12 +63,13 @@ it('calls API', async () => {
 
 ## Key Differences
 
-| Aspect               | cloudflare:test                      | msw-fetch-mock                                    |
-| -------------------- | ------------------------------------ | ------------------------------------------------- |
-| Server lifecycle     | Implicit (managed by test framework) | Explicit (`activate()` / `deactivate()`)          |
-| Call history access  | `fetchMock.getCallHistory()`         | `fetchMock.getCallHistory()` or `fetchMock.calls` |
-| Call history cleanup | Automatic per test                   | Automatic via `assertNoPendingInterceptors()`     |
-| Network connect      | Must call `disableNetConnect()`      | MSW blocks unhandled requests by default          |
-| Runtime              | Cloudflare Workers (workerd)         | Node.js                                           |
+| Aspect               | cloudflare:test                               | msw-fetch-mock                                     |
+| -------------------- | --------------------------------------------- | -------------------------------------------------- |
+| Import               | `import { fetchMock } from 'cloudflare:test'` | `import { fetchMock } from 'msw-fetch-mock'`       |
+| Server lifecycle     | Implicit (managed by test framework)          | Explicit (`activate()` / `deactivate()`)           |
+| Call history access  | `fetchMock.getCallHistory()`                  | `fetchMock.getCallHistory()` or `fetchMock.calls`  |
+| Call history cleanup | Automatic per test                            | Automatic via `assertNoPendingInterceptors()`      |
+| Unhandled requests   | Must call `disableNetConnect()`               | `onUnhandledRequest: 'error'` by default (rejects) |
+| Runtime              | Cloudflare Workers (workerd)                  | Node.js                                            |
 
 > **Note:** `getCallHistory()` and `clearCallHistory()` are provided as Cloudflare-compatible aliases. You can use either the Cloudflare-style methods or the `fetchMock.calls` getter — they are equivalent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msw-fetch-mock",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Undici-style fetch mock API built on MSW (Mock Service Worker)",
   "type": "module",
   "license": "MIT",