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

package/src/node.ts

@@ -0,0 +1,61 @@
+/**
+ * Node entry: `@r0hitsharma/http-client-msw/node`.
+ *
+ * Kept behind its own subpath so an app bundle never resolves `msw/node`, whose
+ * interceptors patch node's http modules.
+ */
+
+import { setupServer, type SetupServer } from 'msw/node';
+
+import type { MockSetup } from './setup.js';
+
+export type MockServerOptions = NonNullable<
+  Parameters<SetupServer['listen']>[0]
+>;
+
+export type MockServer = {
+  /** The underlying msw server, for `use()` and lifecycle events. */
+  server: SetupServer;
+  /** Starts interception. `onUnhandledRequest` defaults to `'error'`. */
+  listen: (overrides?: MockServerOptions) => void;
+  close: () => void;
+  /** Runs the setup's state resets, then drops runtime handler overrides. */
+  reset: () => void;
+};
+
+/**
+ * Serves a {@link MockSetup} from msw's node interceptors — the same handler
+ * array a browser worker serves.
+ *
+ * ```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);
+ *
+ * beforeAll(() => mockServer.listen());
+ * afterEach(() => mockServer.reset());
+ * afterAll(() => mockServer.close());
+ * ```
+ *
+ * `onUnhandledRequest` defaults to `'error'` rather than msw's `'warn'`: in a
+ * test suite an unmocked request is a hole in the fixtures, and a warning that
+ * scrolls past is how a test ends up asserting against real network output.
+ */
+export function setupMockServer(mocks: MockSetup): MockServer {
+  const server = setupServer(...mocks.handlers);
+
+  return {
+    server,
+    listen: (overrides) =>
+      server.listen({ onUnhandledRequest: 'error', ...overrides }),
+    close: () => server.close(),
+    reset: () => {
+      mocks.resetState();
+      server.resetHandlers();
+    },
+  };
+}

package/src/seeded-rng.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSeededRng } from './seeded-rng.js';
+
+const take = (count: number, seed: number): number[] => {
+  const rng = createSeededRng(seed);
+
+  return Array.from({ length: count }, () => rng.next());
+};
+
+describe('createSeededRng', () => {
+  it('produces values in [0, 1)', () => {
+    for (const value of take(200, 7)) {
+      expect(value).toBeGreaterThanOrEqual(0);
+      expect(value).toBeLessThan(1);
+    }
+  });
+
+  it('is deterministic for a seed', () => {
+    expect(take(20, 42)).toEqual(take(20, 42));
+  });
+
+  it('differs between seeds', () => {
+    expect(take(20, 42)).not.toEqual(take(20, 43));
+  });
+
+  it('does not immediately repeat itself', () => {
+    const values = take(200, 1);
+
+    expect(new Set(values).size).toBe(values.length);
+  });
+
+  it('rewinds to the seed on reset', () => {
+    const rng = createSeededRng(99);
+    const first = [rng.next(), rng.next(), rng.next()];
+
+    rng.reset();
+
+    expect([rng.next(), rng.next(), rng.next()]).toEqual(first);
+  });
+
+  it('draws inclusive integers', () => {
+    const rng = createSeededRng(5);
+    const drawn = new Set(Array.from({ length: 300 }, () => rng.int(1, 3)));
+
+    expect([...drawn].sort()).toEqual([1, 2, 3]);
+  });
+
+  it('picks a member of the list', () => {
+    const rng = createSeededRng(5);
+    const items = ['a', 'b', 'c'] as const;
+
+    for (let i = 0; i < 50; i++) {
+      expect(items).toContain(rng.pick(items));
+    }
+  });
+
+  it('refuses to pick from an empty list', () => {
+    expect(() => createSeededRng(1).pick([])).toThrow(
+      /cannot pick from an empty list/,
+    );
+  });
+
+  it('shuffles a copy, deterministically, keeping every element', () => {
+    const items = [1, 2, 3, 4, 5, 6, 7, 8];
+    const shuffled = createSeededRng(3).shuffle(items);
+
+    expect(items).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+    expect([...shuffled].sort((a, b) => a - b)).toEqual(items);
+    expect(shuffled).not.toEqual(items);
+    expect(shuffled).toEqual(createSeededRng(3).shuffle(items));
+  });
+
+  it('picks an `undefined` element rather than reporting an empty list', () => {
+    // `T` may include `undefined`. Guarding on the read instead of on the
+    // length turned a legal pick into a spurious "empty list" throw.
+    expect(createSeededRng(5).pick([undefined])).toBeUndefined();
+  });
+
+  it('shuffles by position, not by value', () => {
+    // The swap must not be skipped for `undefined` elements: the draw is
+    // consumed either way, so skipping would make the ordering depend on the
+    // values and break the reproducibility this generator exists to provide.
+    const withHoles = [1, undefined, 3, undefined, 5, 6, 7, 8];
+    const positions = [1, 2, 3, 4, 5, 6, 7, 8];
+
+    const shuffledHoles = createSeededRng(3).shuffle(withHoles);
+    const shuffledPositions = createSeededRng(3).shuffle(positions);
+
+    // Same seed, same length → the same permutation of indices, whatever the
+    // elements are.
+    expect(shuffledHoles).toEqual(
+      shuffledPositions.map((p) => withHoles[p - 1]),
+    );
+  });
+
+  it('gives the same sequence to a reset instance and a fresh one', () => {
+    const reused = createSeededRng(11);
+    void reused.next();
+    reused.reset();
+
+    expect(reused.shuffle([1, 2, 3, 4])).toEqual(
+      createSeededRng(11).shuffle([1, 2, 3, 4]),
+    );
+  });
+});

package/src/seeded-rng.ts

@@ -0,0 +1,77 @@
+/**
+ * Deterministic randomness for generated fixtures. `Math.random` in a mock makes
+ * a failing test unreproducible and a visual snapshot unstable; a seeded
+ * generator gives varied-looking data that is identical on every run and on every
+ * machine.
+ */
+
+export type SeededRng = {
+  /** The next value in `[0, 1)`. */
+  next: () => number;
+  /**
+   * An integer in `[min, max]`, both inclusive. Bounds are trusted: `max` below
+   * `min` returns a value outside either, unchecked.
+   */
+  int: (min: number, max: number) => number;
+  /** One element. Throws on an empty list. */
+  pick: <T>(items: readonly T[]) => T;
+  /** A shuffled copy; the input is left alone. */
+  shuffle: <T>(items: readonly T[]) => T[];
+  /** Rewinds to the seed. Pass this to `setupMocks({ onReset })`. */
+  reset: () => void;
+};
+
+/**
+ * A mulberry32 generator — 32 bits of state, a handful of integer ops, no
+ * dependency. Its statistical quality is irrelevant here; reproducibility and
+ * being cheap enough to call inside a request handler are the requirements.
+ */
+export function createSeededRng(seed: number): SeededRng {
+  let state = seed >>> 0;
+
+  const next = (): number => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+
+    return ((t ^ (t >>> 14)) >>> 0) / 4_294_967_296;
+  };
+
+  const int = (min: number, max: number): number =>
+    min + Math.floor(next() * (max - min + 1));
+
+  return {
+    next,
+    int,
+    pick: <T>(items: readonly T[]): T => {
+      // Guard on length, not on the read being `undefined`: `T` may itself
+      // include `undefined`, and `pick([undefined, 1])` must return the element
+      // rather than report an empty list.
+      if (items.length === 0) {
+        throw new Error('http-client-msw: cannot pick from an empty list');
+      }
+
+      return items[int(0, items.length - 1)] as T;
+    },
+    shuffle: <T>(items: readonly T[]): T[] => {
+      const shuffled = [...items];
+
+      for (let i = shuffled.length - 1; i > 0; i--) {
+        const j = int(0, i);
+        // Both indices are in range by the loop bound, so the swap is
+        // unconditional — skipping it on an `undefined` *element* would let the
+        // result depend on the values while still consuming the draw above,
+        // which is exactly the reproducibility this generator exists to give.
+        const a = shuffled[i] as T;
+        shuffled[i] = shuffled[j] as T;
+        shuffled[j] = a;
+      }
+
+      return shuffled;
+    },
+    reset: () => {
+      state = seed >>> 0;
+    },
+  };
+}

package/src/setup.test.ts

@@ -0,0 +1,137 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { createMockApi } from './mock-api.js';
+import { createMockStore } from './mock-store.js';
+import { setupMockServer } from './node.js';
+import { createSeededRng } from './seeded-rng.js';
+import { setupMocks } from './setup.js';
+import { type Thing, type TestPaths, seedThings } from './test-fixtures.js';
+
+const mock = createMockApi<TestPaths>({ baseUrl: '/api' });
+
+describe('setupMocks', () => {
+  it('runs reset callbacks in declaration order', () => {
+    const calls: string[] = [];
+    const mocks = setupMocks([], {
+      onReset: [() => calls.push('first'), () => calls.push('second')],
+    });
+
+    mocks.resetState();
+    mocks.resetState();
+
+    expect(calls).toEqual(['first', 'second', 'first', 'second']);
+  });
+
+  it('is inert without reset callbacks', () => {
+    const handler = mock.get('/things', ({ response }) =>
+      response(200).json([]),
+    );
+
+    expect(() => setupMocks([handler]).resetState()).not.toThrow();
+  });
+
+  it('re-seeds identically when an rng feeding a store is rewound first', () => {
+    const rng = createSeededRng(1337);
+    const sized = createMockStore(() =>
+      seedThings().map((thing) => ({ ...thing, size: rng.int(1, 100) })),
+    );
+    const sizes = (): number[] => sized.list().map((thing) => thing.size);
+
+    const ordered = setupMocks([], { onReset: [rng.reset, sized.reset] });
+    const initial = sizes();
+
+    ordered.resetState();
+    expect(sizes()).toEqual(initial);
+    ordered.resetState();
+    expect(sizes()).toEqual(initial);
+  });
+
+  it('drifts when the store is rewound before the rng it draws from', () => {
+    // The failure mode the option's docs warn about, pinned so the ordering
+    // advice cannot quietly stop being true.
+    const rng = createSeededRng(1337);
+    const sized = createMockStore(() =>
+      seedThings().map((thing) => ({ ...thing, size: rng.int(1, 100) })),
+    );
+    const sizes = (): number[] => sized.list().map((thing) => thing.size);
+
+    const misordered = setupMocks([], { onReset: [sized.reset, rng.reset] });
+    const initial = sizes();
+
+    misordered.resetState();
+
+    expect(sizes()).not.toEqual(initial);
+  });
+});
+
+describe('setupMockServer', () => {
+  /** Mutable state a handler writes to, standing in for a mock store. */
+  let things: Thing[] = seedThings();
+  const mocks = setupMocks(
+    [
+      mock.get('/things', ({ response }) => response(200).json(things)),
+      mock.post('/things', async ({ request, response }) => {
+        const created = {
+          id: `t${things.length + 1}`,
+          ...(await request.json()),
+        };
+        things = [...things, created];
+
+        return response(201).json(created);
+      }),
+    ],
+    { onReset: [() => (things = seedThings())] },
+  );
+
+  const mockServer = setupMockServer(mocks);
+
+  beforeAll(() => mockServer.listen());
+  afterAll(() => mockServer.close());
+
+  const list = async (): Promise<Thing[]> =>
+    (await (await fetch('http://localhost/api/things')).json()) as Thing[];
+
+  it('serves the setup handlers', async () => {
+    expect(await list()).toEqual(seedThings());
+  });
+
+  it('reset() clears state written by a previous test', async () => {
+    await fetch('http://localhost/api/things', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Third', size: 3 }),
+    });
+    expect(await list()).toHaveLength(3);
+
+    mockServer.reset();
+
+    expect(await list()).toEqual(seedThings());
+  });
+
+  it('reset() also drops runtime handler overrides', async () => {
+    mockServer.server.use(
+      mock.get('/things', ({ response }) =>
+        response(500).json({ message: 'x' }),
+      ),
+    );
+    expect((await fetch('http://localhost/api/things')).status).toBe(500);
+
+    mockServer.reset();
+
+    expect((await fetch('http://localhost/api/things')).status).toBe(200);
+  });
+
+  it('errors on an unhandled request by default', async () => {
+    await expect(fetch('http://localhost/api/unmocked')).rejects.toThrow();
+  });
+
+  it('takes a listen override for the unhandled-request strategy', () => {
+    const listen = vi.fn();
+    const overridden = setupMockServer(mocks);
+    overridden.server.listen = listen;
+
+    overridden.listen({ onUnhandledRequest: 'bypass' });
+
+    expect(listen).toHaveBeenCalledWith({ onUnhandledRequest: 'bypass' });
+  });
+});

package/src/setup.ts

@@ -0,0 +1,71 @@
+import type { RequestHandler, WebSocketHandler } from 'msw';
+
+/**
+ * Anything msw accepts as a handler. Typed handlers from `createMockApi` are
+ * `RequestHandler`s; the union leaves room for a websocket mock in the same
+ * array without a second setup path.
+ */
+export type MockSetupHandler = RequestHandler | WebSocketHandler;
+
+/**
+ * A callback that returns mock state to its seeded starting point. Stores built
+ * with `createMockStore` expose exactly this as `store.reset`.
+ */
+export type MockResetCallback = () => void;
+
+export type MockSetupOptions = {
+  /**
+   * Callbacks that restore mock state, run **in declaration order** by `reset()`
+   * on whichever entry serves these handlers. This is how a stateful mock stops
+   * leaking writes from one test into the next: the handlers close over a store,
+   * and the store's `reset` is declared here once rather than at every call site.
+   *
+   * Order matters when one reset feeds another. A store whose seed function draws
+   * from a seeded rng must be listed *after* that rng, or each reset re-seeds
+   * from wherever the previous one left the sequence.
+   */
+  onReset?: readonly MockResetCallback[];
+};
+
+/**
+ * An environment-neutral description of a mock deployment: the handler array
+ * plus the state resets that belong with it. It holds no msw setup object of its
+ * own, which is what lets the same value be handed to the browser entry
+ * (`setupWorker`) or the node entry (`setupServer`) without either environment's
+ * msw import reaching the other's bundle.
+ */
+export type MockSetup = {
+  handlers: readonly MockSetupHandler[];
+  /** Runs every `onReset` callback in declaration order. */
+  resetState: () => void;
+};
+
+/**
+ * Bundles handlers with their state resets.
+ *
+ * ```ts
+ * const rng = createSeededRng(42);
+ * const things = createMockStore(() => [
+ *   { id: 't1', name: 'First', size: rng.int(1, 100) },
+ * ]);
+ *
+ * export const mocks = setupMocks(
+ *   [mock.get('/things', ({ response }) => response(200).json(things.list()))],
+ *   // The rng first: the store's seed draws from it.
+ *   { onReset: [rng.reset, things.reset] },
+ * );
+ * ```
+ */
+export function setupMocks(
+  handlers: readonly MockSetupHandler[],
+  options: MockSetupOptions = {},
+): MockSetup {
+  const onReset = options.onReset ?? [];
+
+  return {
+    handlers,
+    resetState: () => {
+      for (const reset of onReset) reset();
+    },
+  };
+}

package/src/test-fixtures.ts

@@ -0,0 +1,113 @@
+/**
+ * Test-only fixtures. Excluded from `tsconfig.build.json` alongside the specs,
+ * so nothing here ships, but still covered by `type:check` — which matters,
+ * because `TestPaths` mirrors `openapi-typescript` output closely enough (every
+ * HTTP method present, absent ones as `?: never`, no-content responses as
+ * `content?: never`) to prove the handler factory's inference against a real
+ * generated `paths` type.
+ */
+
+export type Thing = { id: string; name: string; size: number };
+export type ApiFault = { message: string };
+export type ValidationFault = { message: string; field: string };
+
+type NoBody = { requestBody?: never };
+type NoParams = {
+  query?: never;
+  header?: never;
+  path?: never;
+  cookie?: never;
+};
+
+export type TestPaths = {
+  '/things': {
+    parameters: NoParams;
+    get: NoBody & {
+      parameters: {
+        query?: { limit?: number; tag?: string[] };
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      responses: {
+        200: {
+          headers: Record<string, unknown>;
+          content: { 'application/json': Thing[] };
+        };
+        500: {
+          headers: Record<string, unknown>;
+          content: { 'application/json': ApiFault };
+        };
+      };
+    };
+    post: {
+      parameters: NoParams;
+      requestBody: {
+        content: { 'application/json': { name: string; size: number } };
+      };
+      responses: {
+        201: {
+          headers: Record<string, unknown>;
+          content: { 'application/json': Thing };
+        };
+        422: {
+          headers: Record<string, unknown>;
+          content: { 'application/json': ValidationFault };
+        };
+      };
+    };
+    put?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  '/things/{id}': {
+    parameters: NoParams;
+    get: NoBody & {
+      parameters: {
+        query?: { expand?: string };
+        header?: never;
+        path: { id: string };
+        cookie?: never;
+      };
+      responses: {
+        200: {
+          headers: Record<string, unknown>;
+          content: { 'application/json': Thing };
+        };
+        404: {
+          headers: Record<string, unknown>;
+          content: { 'application/json': ApiFault };
+        };
+      };
+    };
+    delete: NoBody & {
+      parameters: {
+        query?: never;
+        header?: never;
+        path: { id: string };
+        cookie?: never;
+      };
+      responses: {
+        204: { headers: Record<string, unknown>; content?: never };
+        404: {
+          headers: Record<string, unknown>;
+          content: { 'application/json': ApiFault };
+        };
+      };
+    };
+    put?: never;
+    post?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+};
+
+export const seedThings = (): Thing[] => [
+  { id: 't1', name: 'First', size: 1 },
+  { id: 't2', name: 'Second', size: 2 },
+];

package/src/worker-options.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  buildWorkerStartOptions,
+  createIdempotentStart,
+} from './worker-options.js';
+
+describe('buildWorkerStartOptions', () => {
+  it('bypasses unhandled requests and stays quiet by default', () => {
+    expect(buildWorkerStartOptions()).toEqual({
+      onUnhandledRequest: 'bypass',
+      quiet: true,
+      serviceWorker: { url: '/mockServiceWorker.js' },
+    });
+  });
+
+  it('resolves the worker script under the app base path', () => {
+    expect(buildWorkerStartOptions({ baseUrl: '/app/' }).serviceWorker).toEqual(
+      {
+        url: '/app/mockServiceWorker.js',
+      },
+    );
+  });
+
+  it('honours explicit overrides', () => {
+    expect(
+      buildWorkerStartOptions({ onUnhandledRequest: 'warn', quiet: false }),
+    ).toMatchObject({ onUnhandledRequest: 'warn', quiet: false });
+  });
+
+  it('lets the start escape hatch win, including the script url', () => {
+    expect(
+      buildWorkerStartOptions({
+        baseUrl: '/app/',
+        start: {
+          onUnhandledRequest: 'error',
+          serviceWorker: { url: '/custom/worker.js' },
+        },
+      }),
+    ).toEqual({
+      onUnhandledRequest: 'error',
+      quiet: true,
+      serviceWorker: { url: '/custom/worker.js' },
+    });
+  });
+
+  it('keeps the defaults when a forwarded start passes undefined', () => {
+    expect(
+      buildWorkerStartOptions({
+        start: { onUnhandledRequest: undefined, quiet: undefined },
+      }),
+    ).toEqual({
+      onUnhandledRequest: 'bypass',
+      quiet: true,
+      serviceWorker: { url: '/mockServiceWorker.js' },
+    });
+  });
+
+  it('keeps the resolved script url when start sets other worker options', () => {
+    expect(
+      buildWorkerStartOptions({
+        baseUrl: '/app',
+        start: { serviceWorker: { options: { scope: '/app' } } },
+      }).serviceWorker,
+    ).toEqual({ url: '/app/mockServiceWorker.js', options: { scope: '/app' } });
+  });
+
+  it('keeps it when a forwarded serviceWorker passes url: undefined', () => {
+    expect(
+      buildWorkerStartOptions({
+        baseUrl: '/app',
+        start: {
+          serviceWorker: { url: undefined, options: { scope: '/app' } },
+        },
+      }).serviceWorker,
+    ).toEqual({ url: '/app/mockServiceWorker.js', options: { scope: '/app' } });
+  });
+});
+
+describe('createIdempotentStart', () => {
+  it('registers once across repeated calls', async () => {
+    const run = vi.fn(() => Promise.resolve());
+    const { start } = createIdempotentStart(run);
+
+    await Promise.all([start(), start()]);
+    await start();
+
+    expect(run).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns the same promise to concurrent callers', () => {
+    const { start } = createIdempotentStart(() => Promise.resolve());
+
+    expect(start()).toBe(start());
+  });
+
+  it('allows a retry after a failed start', async () => {
+    const run = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValueOnce(new Error('no worker script'))
+      .mockResolvedValueOnce(undefined);
+    const { start } = createIdempotentStart(run);
+
+    await expect(start()).rejects.toThrow('no worker script');
+    await expect(start()).resolves.toBeUndefined();
+
+    expect(run).toHaveBeenCalledTimes(2);
+  });
+
+  it('runs again after invalidate(), which is how stop() re-registers', async () => {
+    const run = vi.fn(() => Promise.resolve());
+    const { start, invalidate } = createIdempotentStart(run);
+
+    await start();
+    invalidate();
+    await start();
+
+    expect(run).toHaveBeenCalledTimes(2);
+  });
+
+  it('rejects rather than throwing when the start function throws synchronously', async () => {
+    const { start } = createIdempotentStart(() => {
+      throw new Error('registration is unavailable');
+    });
+
+    await expect(start()).rejects.toThrow('registration is unavailable');
+  });
+});