@r0hitsharma/http-client-msw 0.12.0-rohit-fork-ci.1

package/README.md

@@ -0,0 +1,251 @@
+# @r0hitsharma/http-client-msw
+
+Typed [msw](https://mswjs.io) mocks for `@r0hitsharma/http-client-core`.
+
+The generated OpenAPI `paths` type **is** the endpoint definition. The same type
+that drives `createApiClient` and `createQueryApi` drives the mock handlers, so a
+handler path, its params, and the body it answers with are checked against the
+contract — a fixture that no longer matches the API fails to typecheck instead of
+quietly making every test that reads it a false pass. See
+[DESIGN.md](./DESIGN.md) for the contract, the `openapi-msw` verdict, and the
+deliberate limits.
+
+## Installation
+
+```bash
+npm install -D @r0hitsharma/http-client-msw msw
+```
+
+`msw` is a peer dependency: the service worker script is generated from the
+installed msw and version-checked at start, so the app has to own the version.
+
+Generate the worker script once and commit it:
+
+```bash
+npx msw init public --save
+```
+
+`public/mockServiceWorker.js` is a build artifact that belongs in git — the app
+serves it, and `--save` records the path in `package.json` so msw warns when an
+upgrade leaves it stale. Adjust `public` if the bundler serves static files from
+elsewhere.
+
+## Usage
+
+### 1. Generate types
+
+```bash
+npx uikit-openapi-generate --schema openapi.json --output src/api.types.ts
+```
+
+The same `src/api.types.ts` the client and query layer already use. Nothing about
+the mocks is described twice.
+
+### 2. Write the handlers
+
+Keep them in one module — a `src/mocks/` folder in the app, or a workspace
+package (`@your-scope/api-mocks`) when a Playwright suite and a unit-test suite
+both consume them:
+
+```ts
+// src/mocks/index.ts
+import {
+  createMockApi,
+  createMockStore,
+  createSeededRng,
+  mockDelay,
+  setupMocks,
+} from '@r0hitsharma/http-client-msw';
+
+import type { paths } from '../api.types';
+
+// The same baseUrl the app passes to `createApiClient`.
+const mock = createMockApi<paths>({ baseUrl: '/api' });
+
+const rng = createSeededRng(1337);
+const positions = createMockStore(() =>
+  Array.from({ length: 8 }, (_, index) => ({
+    id: `p${index + 1}`,
+    label: `Position ${index + 1}`,
+    health: rng.int(50, 200) / 100,
+  })),
+);
+
+export const mocks = setupMocks(
+  [
+    mock.get('/positions', async ({ query, response }) => {
+      await mockDelay(300);
+      const limit = Number(query.get('limit') ?? '25');
+
+      return response(200).json(positions.list().slice(0, limit));
+    }),
+
+    mock.get('/positions/{id}', ({ params, response }) => {
+      const position = positions.get(params.id);
+
+      // Both branches are checked: 200 takes a Position, 404 takes the
+      // operation's own error body.
+      return position
+        ? response(200).json(position)
+        : response(404).json({ message: `no position ${params.id}` });
+    }),
+
+    mock.post('/positions/{id}/close', ({ params, response }) =>
+      positions.remove(params.id)
+        ? response(204).empty()
+        : response(404).json({ message: 'already closed' }),
+    ),
+  ],
+  // Everything a handler writes to is restored by `reset()`. Order matters:
+  // callbacks run as declared, and the store's seed function draws from the rng,
+  // so the rng has to be rewound first or each reset re-seeds from a different
+  // point in the sequence.
+  { onReset: [rng.reset, positions.reset] },
+);
+```
+
+For a route the OpenAPI document does not describe at all — an auth callback on
+another host, say — `mock.untyped` is msw's own `http` object, and
+`response.untyped(new Response(...))` returns an arbitrary response from a typed
+handler.
+
+### 3. Run them in the browser (dev, and Playwright)
+
+Start the worker **before** rendering, so no component can fire a request the
+worker is not yet intercepting:
+
+```tsx
+// src/main.tsx
+import { createRoot } from 'react-dom/client';
+
+import { App } from './App';
+
+if (import.meta.env.VITE_API_MOCKS === '1') {
+  const { setupMockWorker } = await import(
+    '@r0hitsharma/http-client-msw/browser'
+  );
+  const { mocks } = await import('./mocks');
+
+  // `baseUrl` here is the app's public base path, not the API base: it locates
+  // `mockServiceWorker.js` for a subpath deployment.
+  const mockWorker = setupMockWorker(mocks, {
+    baseUrl: import.meta.env.BASE_URL,
+  });
+
+  // Reachable from a Playwright test; see below.
+  Object.assign(window, { resetMocks: () => mockWorker.reset() });
+
+  await mockWorker.start();
+}
+
+createRoot(document.getElementById('root')!).render(<App />);
+```
+
+```bash
+VITE_API_MOCKS=1 npm run dev
+```
+
+The gate matters as much as the mocks. Vite replaces `import.meta.env.VITE_*`
+statically, so with the flag unset the whole branch is dead code and neither msw
+nor the fixtures reach a production bundle — which is only true because both
+imports are dynamic and behind the check. A runtime `process.env` read or a
+static `import` of the mocks module would bundle them either way.
+
+`start()` is idempotent, so a hot reload or a test fixture may call it again
+without re-registering the worker. `stop()` releases that, so a later `start()`
+registers again rather than resolving into a stopped worker.
+
+For a Playwright suite, serve the app with the same flag on — the browser worker
+answers from the same handlers — and reset between tests through the hook the
+entry exposed:
+
+```ts
+// tests/positions.spec.ts
+declare global {
+  interface Window {
+    resetMocks?: () => void;
+  }
+}
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('/');
+  await page.evaluate(() => window.resetMocks?.());
+});
+```
+
+A full reload re-runs the entry and re-seeds the stores anyway; the explicit
+`resetMocks()` matters when a test navigates within the app instead.
+
+### 4. Run them in vitest
+
+Same handler array, node interceptors:
+
+```ts
+// src/test-setup.ts
+import { setupMockServer } from '@r0hitsharma/http-client-msw/node';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+
+import { mocks } from './mocks';
+
+const mockServer = setupMockServer(mocks);
+
+// `onUnhandledRequest` defaults to 'error': an unmocked request in a suite is a
+// hole in the fixtures, not something to warn about and scroll past.
+beforeAll(() => mockServer.listen());
+afterEach(() => mockServer.reset());
+afterAll(() => mockServer.close());
+```
+
+```ts
+// vitest.config.ts
+export default defineConfig({
+  test: { setupFiles: ['./src/test-setup.ts'] },
+});
+```
+
+`reset()` covers both kinds of leakage between tests: state a handler wrote, and
+handlers a test installed with `mockServer.server.use(...)`.
+
+An origin-relative `baseUrl` works in both environments because handler paths are
+matched on any origin by default — msw would otherwise leave a relative path
+unmatched under `setupServer`, where every request URL is absolute. Pass
+`origin: 'exact'` to `createMockApi` to opt out; see
+[DESIGN.md](./DESIGN.md#handler-path-and-origin-matching).
+
+## API surface
+
+| Export | What it does |
+| --- | --- |
+| `createMockApi<TPaths>(options?)` | Typed handler factories per method, plus `untyped` |
+| `setupMocks(handlers, options?)` | Bundles handlers with their state resets, environment-neutral |
+| `setupMockWorker(mocks, options?)` | **`/browser`.** Serves them from a service worker; idempotent `start()` |
+| `setupMockServer(mocks)` | **`/node`.** Serves them from msw's node interceptors |
+| `createMockStore(seedFn, options?)` | In-memory collection so a write shows up in the next read |
+| `createSeededRng(seed)` | Deterministic PRNG for reproducible generated fixtures |
+| `mockDelay(ms \| { test, dev })` | Env-aware latency; no delay under test by default |
+| `resolveMockDelay` / `isTestEnvironment` | The delay decision, for a consumer's own helpers |
+| `resolveWorkerScriptUrl` / `normalizeApiBaseUrl` / `resolveHandlerBase` / `isAbsoluteUrl` | The URL primitives |
+| `buildWorkerStartOptions` / `createIdempotentStart` | **`/browser`.** The start decisions, unit-testable |
+
+Handler and resolver types are re-exported as `MockHandler`,
+`MockResponseResolver`, `MockPathsFor`, `MockRequestBodyFor`, and
+`MockResponseBodyFor`, so a helper written around a resolver types against the
+same msw copy this package resolves.
+
+## Not in v1
+
+Handlers generated from the OpenAPI document, runtime request-body validation,
+named scenario switching, GraphQL/websocket typing, per-test handler isolation
+via msw's `boundary`, and fault injection are deliberately out of scope — see
+[DESIGN.md](./DESIGN.md#deliberately-out-of-v1).
+
+## Peer dependencies
+
+- `msw` (`^2.10.5`)
+
+## See also
+
+- [http-client-core](../http-client-core) for the client factory, the OpenAPI
+  type generator, and the zod helpers
+- [http-client-react](../http-client-react) for the TanStack Query layer keyed off
+  the same `paths` type

package/dist/base-url.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Two different base URLs live in this package and they normalize to opposite
+ * shapes, so both live here rather than being inlined at their call sites:
+ *
+ * - the **API** base (`createMockApi({ baseUrl })`) is prepended to OpenAPI path
+ *   templates, which already start with `/`, so it must not end in one;
+ * - the **app** base (`setupMockWorker(mocks, { baseUrl })`) is the public base
+ *   path a subpath deployment is served from, and the worker script filename is
+ *   appended to it, so it must end in one.
+ */
+/** How an origin-relative API base is matched. See {@link resolveHandlerBase}. */
+export type MockOriginMatching = 'any' | 'exact';
+/**
+ * Whether the base carries its own scheme. A protocol-relative `//host` does
+ * not, and so is *not* absolute here — see {@link resolveHandlerBase}, which
+ * has to prefix one for msw to match it at all.
+ */
+export declare function isAbsoluteUrl(url: string): boolean;
+/** Strips trailing slashes so `${base}${'/things'}` never doubles up. */
+export declare function normalizeApiBaseUrl(baseUrl?: string): string;
+/**
+ * The prefix every handler path is built on.
+ *
+ * msw resolves a relative handler path against `document.baseURI` in the browser
+ * and leaves it relative in node, where request URLs are always absolute — so a
+ * relative path silently matches nothing under `setupServer`. Prefixing an
+ * origin-relative base with msw's `*` wildcard makes one handler array match in
+ * both, which is what lets the same mocks serve dev, vitest, and Playwright.
+ *
+ * `'exact'` opts out and keeps the path relative — same-origin matching only,
+ * and node tests then need an absolute `baseUrl`. An absolute base already pins
+ * the origin, so the setting does not apply to one.
+ *
+ * A protocol-relative `//host` is prefixed under *both* settings. It pins the
+ * host but not the scheme, and msw matches a bare `//host` pattern against
+ * neither `http:` nor `https:` — the request escapes to the real network. The
+ * wildcard stands in for the scheme only, so the host stays pinned.
+ */
+export declare function resolveHandlerBase(baseUrl: string | undefined, origin: MockOriginMatching): string;
+/**
+ * The URL msw's service worker script is served from. It follows the app's
+ * public base path — `import.meta.env.BASE_URL` under Vite — because a bundler
+ * copies `public/mockServiceWorker.js` to `${base}mockServiceWorker.js`, and the
+ * worker's scope is limited to the directory it is served from.
+ */
+export declare function resolveWorkerScriptUrl(baseUrl?: string): string;

package/dist/base-url.js

@@ -0,0 +1,65 @@
+/**
+ * Two different base URLs live in this package and they normalize to opposite
+ * shapes, so both live here rather than being inlined at their call sites:
+ *
+ * - the **API** base (`createMockApi({ baseUrl })`) is prepended to OpenAPI path
+ *   templates, which already start with `/`, so it must not end in one;
+ * - the **app** base (`setupMockWorker(mocks, { baseUrl })`) is the public base
+ *   path a subpath deployment is served from, and the worker script filename is
+ *   appended to it, so it must end in one.
+ */
+/** A scheme plus authority — `https://api.test`. Pins both scheme and host. */
+const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:\/\//i;
+/** A protocol-relative `//api.test` — pins the host, leaves the scheme open. */
+const PROTOCOL_RELATIVE_URL = /^\/\//;
+/**
+ * Whether the base carries its own scheme. A protocol-relative `//host` does
+ * not, and so is *not* absolute here — see {@link resolveHandlerBase}, which
+ * has to prefix one for msw to match it at all.
+ */
+export function isAbsoluteUrl(url) {
+    return ABSOLUTE_URL.test(url);
+}
+/** Strips trailing slashes so `${base}${'/things'}` never doubles up. */
+export function normalizeApiBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return '';
+    return baseUrl.replace(/\/+$/, '');
+}
+/**
+ * The prefix every handler path is built on.
+ *
+ * msw resolves a relative handler path against `document.baseURI` in the browser
+ * and leaves it relative in node, where request URLs are always absolute — so a
+ * relative path silently matches nothing under `setupServer`. Prefixing an
+ * origin-relative base with msw's `*` wildcard makes one handler array match in
+ * both, which is what lets the same mocks serve dev, vitest, and Playwright.
+ *
+ * `'exact'` opts out and keeps the path relative — same-origin matching only,
+ * and node tests then need an absolute `baseUrl`. An absolute base already pins
+ * the origin, so the setting does not apply to one.
+ *
+ * A protocol-relative `//host` is prefixed under *both* settings. It pins the
+ * host but not the scheme, and msw matches a bare `//host` pattern against
+ * neither `http:` nor `https:` — the request escapes to the real network. The
+ * wildcard stands in for the scheme only, so the host stays pinned.
+ */
+export function resolveHandlerBase(baseUrl, origin) {
+    const normalized = normalizeApiBaseUrl(baseUrl);
+    if (isAbsoluteUrl(normalized))
+        return normalized;
+    const pinsHost = PROTOCOL_RELATIVE_URL.test(normalized);
+    if (origin === 'exact' && !pinsHost)
+        return normalized;
+    return `*${normalized}`;
+}
+/**
+ * The URL msw's service worker script is served from. It follows the app's
+ * public base path — `import.meta.env.BASE_URL` under Vite — because a bundler
+ * copies `public/mockServiceWorker.js` to `${base}mockServiceWorker.js`, and the
+ * worker's scope is limited to the directory it is served from.
+ */
+export function resolveWorkerScriptUrl(baseUrl) {
+    const base = baseUrl && baseUrl.length > 0 ? baseUrl : '/';
+    return `${base.endsWith('/') ? base : `${base}/`}mockServiceWorker.js`;
+}

package/dist/browser.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Browser entry: `@r0hitsharma/http-client-msw/browser`.
+ *
+ * Kept behind its own subpath so `msw/browser` — and the service-worker
+ * machinery it pulls in — never reaches a node test's module graph, and so an
+ * app bundle that imports only this entry does not drag in `msw/node`.
+ */
+import { type SetupWorker } from 'msw/browser';
+import type { MockSetup } from './setup.js';
+import { type MockWorkerOptions } from './worker-options.js';
+/**
+ * Re-exported here rather than from the package root: their types reference
+ * `msw/browser`, which does not resolve under a node-only condition set.
+ */
+export { buildWorkerStartOptions, createIdempotentStart, type IdempotentStart, type MockWorkerOptions, } from './worker-options.js';
+export type MockWorker = {
+    /** The underlying msw worker, for `use()` and lifecycle events. */
+    worker: SetupWorker;
+    /** Registers and activates the worker. Idempotent; safe to await anywhere. */
+    start: () => Promise<void>;
+    /** Stops interception. A later `start()` re-registers the worker. */
+    stop: () => void;
+    /** Runs the setup's state resets, then drops runtime handler overrides. */
+    reset: () => void;
+};
+/**
+ * Serves a {@link MockSetup} from a service worker.
+ *
+ * Call `start()` and await it **before** rendering, so no component can fire a
+ * request the worker is not yet intercepting:
+ *
+ * ```ts
+ * // src/main.tsx
+ * if (import.meta.env.VITE_API_MOCKS === '1') {
+ *   const { setupMockWorker } = await import(
+ *     '@r0hitsharma/http-client-msw/browser'
+ *   );
+ *   const { mocks } = await import('./mocks');
+ *
+ *   await setupMockWorker(mocks, { baseUrl: import.meta.env.BASE_URL }).start();
+ * }
+ *
+ * createRoot(document.getElementById('root')!).render(<App />);
+ * ```
+ *
+ * The dynamic imports are what keep msw and the fixtures out of a production
+ * bundle: with a statically analysable `import.meta.env` flag, the whole branch
+ * is dead code a bundler drops.
+ */
+export declare function setupMockWorker(mocks: MockSetup, options?: MockWorkerOptions): MockWorker;

package/dist/browser.js

@@ -0,0 +1,59 @@
+/**
+ * Browser entry: `@r0hitsharma/http-client-msw/browser`.
+ *
+ * Kept behind its own subpath so `msw/browser` — and the service-worker
+ * machinery it pulls in — never reaches a node test's module graph, and so an
+ * app bundle that imports only this entry does not drag in `msw/node`.
+ */
+import { setupWorker } from 'msw/browser';
+import { buildWorkerStartOptions, createIdempotentStart, } from './worker-options.js';
+/**
+ * Re-exported here rather than from the package root: their types reference
+ * `msw/browser`, which does not resolve under a node-only condition set.
+ */
+export { buildWorkerStartOptions, createIdempotentStart, } from './worker-options.js';
+/**
+ * Serves a {@link MockSetup} from a service worker.
+ *
+ * Call `start()` and await it **before** rendering, so no component can fire a
+ * request the worker is not yet intercepting:
+ *
+ * ```ts
+ * // src/main.tsx
+ * if (import.meta.env.VITE_API_MOCKS === '1') {
+ *   const { setupMockWorker } = await import(
+ *     '@r0hitsharma/http-client-msw/browser'
+ *   );
+ *   const { mocks } = await import('./mocks');
+ *
+ *   await setupMockWorker(mocks, { baseUrl: import.meta.env.BASE_URL }).start();
+ * }
+ *
+ * createRoot(document.getElementById('root')!).render(<App />);
+ * ```
+ *
+ * The dynamic imports are what keep msw and the fixtures out of a production
+ * bundle: with a statically analysable `import.meta.env` flag, the whole branch
+ * is dead code a bundler drops.
+ */
+export function setupMockWorker(mocks, options = {}) {
+    const worker = setupWorker(...mocks.handlers);
+    const startOptions = buildWorkerStartOptions(options);
+    const { start, invalidate } = createIdempotentStart(async () => {
+        await worker.start(startOptions);
+    });
+    return {
+        worker,
+        start,
+        stop: () => {
+            worker.stop();
+            // A stopped worker intercepts nothing, so the next `start()` has to
+            // re-register rather than resolve from the memo.
+            invalidate();
+        },
+        reset: () => {
+            mocks.resetState();
+            worker.resetHandlers();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Typed msw mocks keyed off a generated OpenAPI `paths` type — the same type
+ * that drives `createApiClient` and `createQueryApi`, so handlers, params, and
+ * fixture bodies are checked against one contract.
+ *
+ * Environment wiring lives behind subpath entries so neither environment's msw
+ * import ends up in the other's bundle:
+ *
+ * - `@r0hitsharma/http-client-msw/browser` — `setupMockWorker`
+ * - `@r0hitsharma/http-client-msw/node` — `setupMockServer`
+ *
+ * Nothing here references `msw/browser` or `msw/node`, so this entry stays
+ * resolvable from either environment.
+ */
+export { createMockApi, type MockApi, type MockApiOptions, type MockHandler, type MockOriginMatching, type MockPathsFor, type MockRequestBodyFor, type MockRequestHandler, type MockResponseBodyFor, type MockResponseResolver, type MockResponseResolverInfo, } from './mock-api.js';
+export { isAbsoluteUrl, normalizeApiBaseUrl, resolveHandlerBase, resolveWorkerScriptUrl, } from './base-url.js';
+export { isTestEnvironment, mockDelay, type MockDelayInput, resolveMockDelay, } from './mock-delay.js';
+export { createMockStore, type MockStore, type MockStoreOptions, } from './mock-store.js';
+export { createSeededRng, type SeededRng } from './seeded-rng.js';
+export { type MockResetCallback, type MockSetup, type MockSetupHandler, type MockSetupOptions, setupMocks, } from './setup.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * Typed msw mocks keyed off a generated OpenAPI `paths` type — the same type
+ * that drives `createApiClient` and `createQueryApi`, so handlers, params, and
+ * fixture bodies are checked against one contract.
+ *
+ * Environment wiring lives behind subpath entries so neither environment's msw
+ * import ends up in the other's bundle:
+ *
+ * - `@r0hitsharma/http-client-msw/browser` — `setupMockWorker`
+ * - `@r0hitsharma/http-client-msw/node` — `setupMockServer`
+ *
+ * Nothing here references `msw/browser` or `msw/node`, so this entry stays
+ * resolvable from either environment.
+ */
+export { createMockApi, } from './mock-api.js';
+export { isAbsoluteUrl, normalizeApiBaseUrl, resolveHandlerBase, resolveWorkerScriptUrl, } from './base-url.js';
+export { isTestEnvironment, mockDelay, resolveMockDelay, } from './mock-delay.js';
+export { createMockStore, } from './mock-store.js';
+export { createSeededRng } from './seeded-rng.js';
+export { setupMocks, } from './setup.js';

package/dist/mock-api.d.ts

@@ -0,0 +1,75 @@
+import { type OpenApiHttpHandlers } from 'openapi-msw';
+import { type MockOriginMatching } from './base-url.js';
+/**
+ * The msw handler types this package's surface is expressed in. They are
+ * re-exported so a consumer writing a helper around a resolver types against
+ * the copy of msw this package resolves, rather than importing msw types in one
+ * file and ours in another.
+ */
+export type { HttpHandler as MockHandler, RequestHandler as MockRequestHandler, } from 'msw';
+export type { MockOriginMatching } from './base-url.js';
+export type { ResponseResolver as MockResponseResolver, ResponseResolverInfo as MockResponseResolverInfo, } from 'openapi-msw';
+export type { PathsFor as MockPathsFor, RequestBodyFor as MockRequestBodyFor, ResponseBodyFor as MockResponseBodyFor, } from 'openapi-msw';
+export type MockApiOptions = {
+    /**
+     * Prepended to every handler path, for an API mounted under a prefix. Given
+     * `'/api'`, a handler declared on `/things/{id}` matches `/api/things/:id`.
+     * Pass the same value the app passes to `createApiClient`.
+     *
+     * Either an origin-relative path with a leading slash (`'/api'`) or an absolute
+     * URL (`'https://api.test/v1'`); a trailing slash is tolerated. It is
+     * concatenated with the OpenAPI path, so anything else — a query string, a
+     * fragment, a missing leading slash — yields a pattern that matches nothing,
+     * which surfaces as an unhandled request rather than an error.
+     */
+    baseUrl?: string;
+    /**
+     * How an origin-relative `baseUrl` is matched.
+     *
+     * - `'any'` (default) prefixes handler paths with msw's `*` origin wildcard, so
+     *   one handler array matches both the relative request a browser app makes
+     *   and the absolute URL a node test has to issue. That is what makes the same
+     *   mocks reusable across dev, vitest, and Playwright.
+     * - `'exact'` leaves paths relative: same-origin matching only, and a node
+     *   test then needs an absolute `baseUrl` of its own.
+     *
+     * An absolute `baseUrl` already pins the origin, so this does not apply to
+     * one.
+     */
+    origin?: MockOriginMatching;
+};
+/**
+ * A typed handler factory per HTTP method, plus `untyped` — msw's own `http`
+ * object, for the rare route that is not in the OpenAPI document at all (an
+ * auth callback on another host, say).
+ */
+export type MockApi<TPaths extends object> = OpenApiHttpHandlers<TPaths>;
+/**
+ * Creates typed msw request-handler factories bound to a generated OpenAPI
+ * `paths` type.
+ *
+ * The generated `TPaths` is the only endpoint definition: which methods exist on
+ * which paths, what path and query params they take, and what body each status
+ * may return are all read off it. A handler for a path the API does not have, or
+ * one that answers with a body the operation does not declare, fails to compile
+ * — which is the whole point of the layer, since a fixture that silently drifts
+ * from the contract makes every test that depends on it a false pass.
+ *
+ * `TPaths` must be passed explicitly; there is no value argument to infer it
+ * from — which is why the constraint is `object` rather than the `{}` that
+ * openapi-msw itself accepts. Every primitive but `null` and `undefined`
+ * satisfies `{}`, so a mistyped type argument compiled into a factory offering
+ * no paths at all.
+ *
+ * ```ts
+ * const mock = createMockApi<paths>({ baseUrl: '/api' });
+ *
+ * const handlers = [
+ *   mock.get('/things/{id}', ({ params, response }) =>
+ *     response(200).json({ id: params.id, name: 'Thing' }),
+ *   ),
+ *   mock.get('/things', ({ response }) => response(500).json({ message: 'nope' })),
+ * ];
+ * ```
+ */
+export declare function createMockApi<TPaths extends object>(options?: MockApiOptions): MockApi<TPaths>;

package/dist/mock-api.js

@@ -0,0 +1,35 @@
+import { createOpenApiHttp } from 'openapi-msw';
+import { resolveHandlerBase } from './base-url.js';
+/**
+ * Creates typed msw request-handler factories bound to a generated OpenAPI
+ * `paths` type.
+ *
+ * The generated `TPaths` is the only endpoint definition: which methods exist on
+ * which paths, what path and query params they take, and what body each status
+ * may return are all read off it. A handler for a path the API does not have, or
+ * one that answers with a body the operation does not declare, fails to compile
+ * — which is the whole point of the layer, since a fixture that silently drifts
+ * from the contract makes every test that depends on it a false pass.
+ *
+ * `TPaths` must be passed explicitly; there is no value argument to infer it
+ * from — which is why the constraint is `object` rather than the `{}` that
+ * openapi-msw itself accepts. Every primitive but `null` and `undefined`
+ * satisfies `{}`, so a mistyped type argument compiled into a factory offering
+ * no paths at all.
+ *
+ * ```ts
+ * const mock = createMockApi<paths>({ baseUrl: '/api' });
+ *
+ * const handlers = [
+ *   mock.get('/things/{id}', ({ params, response }) =>
+ *     response(200).json({ id: params.id, name: 'Thing' }),
+ *   ),
+ *   mock.get('/things', ({ response }) => response(500).json({ message: 'nope' })),
+ * ];
+ * ```
+ */
+export function createMockApi(options = {}) {
+    return createOpenApiHttp({
+        baseUrl: resolveHandlerBase(options.baseUrl, options.origin ?? 'any'),
+    });
+}

package/dist/mock-delay.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Latency is what makes a mock exercise the states a real API forces an app
+ * through — pending spinners, skeletons, optimistic UI, race conditions. The same
+ * latency in a test suite is dead time, so the amount is per-environment and the
+ * default under test is none.
+ */
+export type MockDelayInput = number | {
+    /** Milliseconds under test. Defaults to `0`. */
+    test?: number;
+    /** Milliseconds everywhere else. Defaults to `0`. */
+    dev?: number;
+};
+/**
+ * True when running under a test runner: `NODE_ENV === 'test'` (vitest, jest) or
+ * Vite's `MODE === 'test'`. Read defensively because neither `process` nor
+ * `import.meta.env` exists in every environment this package runs in.
+ */
+export declare function isTestEnvironment(): boolean;
+/** The pure resolution `mockDelay` applies, split out so both branches are testable. */
+export declare function resolveMockDelay(input: MockDelayInput, isTest: boolean): number;
+/**
+ * Waits, in dev; resolves immediately under test unless a test delay is asked
+ * for.
+ *
+ * ```ts
+ * mock.get('/things', async ({ response }) => {
+ *   await mockDelay(400);
+ *   return response(200).json(things.list());
+ * });
+ *
+ * // Keep a little latency under test, for a pending-state assertion.
+ * await mockDelay({ dev: 400, test: 10 });
+ * ```
+ */
+export declare function mockDelay(input?: MockDelayInput): Promise<void>;