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

package/src/mock-api.types.test.ts

@@ -0,0 +1,119 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import {
+  createMockApi,
+  type MockPathsFor,
+  type MockRequestBodyFor,
+  type MockResponseBodyFor,
+} from './mock-api.js';
+import type { ApiFault, TestPaths, Thing } from './test-fixtures.js';
+
+/**
+ * Type-level coverage of the guarantee the package exists for: a handler's path,
+ * params, request body, status codes, and response bodies all come off the
+ * generated `TPaths`, so a fixture cannot drift from the contract while still
+ * compiling.
+ *
+ * `expectTypeOf` and `@ts-expect-error` are checked by `npm run type:check`, so
+ * the assertions live in a function that is never called. The `it` block below
+ * only keeps vitest from reporting the file as empty.
+ */
+
+const mock = createMockApi<TestPaths>();
+
+describe('createMockApi — inference', () => {
+  it('is asserted by tsc, not at runtime', () => {
+    expectTypeOf(mock.get).toBeFunction();
+    expectTypeOf(mock.untyped).toBeObject();
+  });
+});
+
+export function typeAssertions(): void {
+  // A type argument that is not an object shape is rejected, rather than
+  // compiling into a factory that offers no paths at all.
+  // @ts-expect-error — a string is not a `paths` type
+  createMockApi<'nonsense'>();
+  // @ts-expect-error — nor is a number
+  createMockApi<7>();
+
+  // Only paths that declare the method are offered per factory.
+  expectTypeOf<MockPathsFor<typeof mock.get>>().toEqualTypeOf<
+    '/things' | '/things/{id}'
+  >();
+  expectTypeOf<MockPathsFor<typeof mock.post>>().toEqualTypeOf<'/things'>();
+  expectTypeOf<
+    MockPathsFor<typeof mock.delete>
+  >().toEqualTypeOf<'/things/{id}'>();
+
+  // Bodies are read off the operation, not restated by the fixture.
+  expectTypeOf<MockResponseBodyFor<typeof mock.get, '/things'>>().toEqualTypeOf<
+    Thing[] | ApiFault
+  >();
+  expectTypeOf<
+    MockRequestBodyFor<typeof mock.post, '/things'>
+  >().toEqualTypeOf<{
+    name: string;
+    size: number;
+  }>();
+
+  mock.get('/things/{id}', ({ params, query, request, response }) => {
+    // Path params are stringified from the operation's `parameters.path`.
+    expectTypeOf(params).toEqualTypeOf<{ id: string }>();
+    // Query params are typed per name; an optional one may be absent.
+    expectTypeOf(query.get('expand')).toEqualTypeOf<string | null>();
+    expectTypeOf(request.url).toBeString();
+
+    return response(200).json({ id: params.id, name: 'Thing', size: 1 });
+  });
+
+  mock.get('/things', ({ query, response }) => {
+    // An array-valued query param stringifies to its element type.
+    expectTypeOf(query.getAll('tag')).toEqualTypeOf<string[]>();
+    expectTypeOf(query.get('limit')).toEqualTypeOf<string | null>();
+
+    return response(200).json([]);
+  });
+
+  mock.post('/things', async ({ request, response }) => {
+    expectTypeOf(await request.json()).toEqualTypeOf<{
+      name: string;
+      size: number;
+    }>();
+
+    return response(201).json({ id: 'new', name: 'New', size: 1 });
+  });
+
+  // A declared error status takes that status's own body shape.
+  mock.get('/things/{id}', ({ response }) =>
+    response(404).json({ message: 'gone' }),
+  );
+
+  // A no-content response takes no body at all.
+  mock.delete('/things/{id}', ({ response }) => response(204).empty());
+
+  // @ts-expect-error — the path is not in TestPaths
+  mock.get('/unknown', ({ response }) => response(200).json([]));
+
+  // @ts-expect-error — /things has no DELETE operation
+  mock.delete('/things', ({ response }) => response(204).empty());
+
+  mock.get('/things/{id}', ({ response }) =>
+    // @ts-expect-error — `size` is required by Thing and `name` must be a string
+    response(200).json({ id: 'x', name: 7 }),
+  );
+
+  mock.get('/things', ({ response }) =>
+    // @ts-expect-error — the 200 response is a list of Thing, not a bare Thing
+    response(200).json({ id: 'x', name: 'Thing', size: 1 }),
+  );
+
+  // @ts-expect-error — 418 is not one of the operation's declared responses
+  mock.get('/things', ({ response }) => response(418).json({ message: 'no' }));
+
+  mock.get('/things', ({ query, response }) => {
+    // @ts-expect-error — 'unknown' is not a declared query param
+    query.get('unknown');
+
+    return response(500).json({ message: 'boom' });
+  });
+}

package/src/mock-delay.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  isTestEnvironment,
+  mockDelay,
+  resolveMockDelay,
+} from './mock-delay.js';
+
+describe('resolveMockDelay', () => {
+  it('skips a plain delay under test and honours it elsewhere', () => {
+    expect(resolveMockDelay(400, true)).toBe(0);
+    expect(resolveMockDelay(400, false)).toBe(400);
+  });
+
+  it('takes the per-environment value from an object', () => {
+    expect(resolveMockDelay({ dev: 400, test: 10 }, true)).toBe(10);
+    expect(resolveMockDelay({ dev: 400, test: 10 }, false)).toBe(400);
+  });
+
+  it('defaults an unspecified environment to no delay', () => {
+    expect(resolveMockDelay({ dev: 400 }, true)).toBe(0);
+    expect(resolveMockDelay({ test: 10 }, false)).toBe(0);
+    expect(resolveMockDelay({}, false)).toBe(0);
+  });
+});
+
+describe('isTestEnvironment', () => {
+  it('detects the runner this suite is running under', () => {
+    expect(isTestEnvironment()).toBe(true);
+  });
+});
+
+describe('mockDelay', () => {
+  it('resolves without a timer under test', async () => {
+    const startedAt = Date.now();
+    await mockDelay(5_000);
+
+    expect(Date.now() - startedAt).toBeLessThan(1_000);
+  });
+
+  it('still waits when a test delay is asked for', async () => {
+    const startedAt = Date.now();
+    await mockDelay({ dev: 5_000, test: 20 });
+
+    expect(Date.now() - startedAt).toBeGreaterThanOrEqual(15);
+  });
+
+  it('resolves immediately with no argument', async () => {
+    await expect(mockDelay()).resolves.toBeUndefined();
+  });
+});

package/src/mock-delay.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 function isTestEnvironment(): boolean {
+  // `process.env` is optional-chained as well as guarded: a browser shim that
+  // defines `process` without an `env` would otherwise throw from inside a
+  // request handler. The dot form is deliberate — it is what bundlers rewrite.
+  const nodeEnv =
+    typeof process === 'undefined' ? undefined : process.env?.NODE_ENV;
+  const viteMode = (import.meta as ImportMeta & { env?: { MODE?: string } }).env
+    ?.MODE;
+
+  return nodeEnv === 'test' || viteMode === 'test';
+}
+
+/** The pure resolution `mockDelay` applies, split out so both branches are testable. */
+export function resolveMockDelay(
+  input: MockDelayInput,
+  isTest: boolean,
+): number {
+  if (typeof input === 'number') return isTest ? 0 : input;
+
+  return (isTest ? input.test : input.dev) ?? 0;
+}
+
+/**
+ * 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 function mockDelay(input: MockDelayInput = 0): Promise<void> {
+  const ms = resolveMockDelay(input, isTestEnvironment());
+
+  // No timer at all for a zero delay: a mock that resolves in the same
+  // microtask keeps a suite's timing behaviour unchanged.
+  if (ms <= 0) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/mock-store.test.ts

@@ -0,0 +1,263 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+import { createMockApi } from './mock-api.js';
+import { createMockStore } from './mock-store.js';
+import { setupMockServer } from './node.js';
+import { setupMocks } from './setup.js';
+import { type Thing, type TestPaths, seedThings } from './test-fixtures.js';
+
+describe('createMockStore', () => {
+  it('starts from the seed, in insertion order', () => {
+    const store = createMockStore(seedThings);
+
+    expect(store.list()).toEqual(seedThings());
+    expect(store.size).toBe(2);
+  });
+
+  it('reads and writes by id', () => {
+    const store = createMockStore(seedThings);
+
+    expect(store.get('t1')?.name).toBe('First');
+    expect(store.has('t9')).toBe(false);
+
+    store.insert({ id: 't3', name: 'Third', size: 3 });
+
+    expect(store.size).toBe(3);
+    expect(store.list().at(-1)?.id).toBe('t3');
+  });
+
+  it('rejects a duplicate id as a fixture bug', () => {
+    const store = createMockStore(seedThings);
+
+    expect(() => store.insert({ id: 't1', name: 'Clash', size: 0 })).toThrow(
+      /already holds an item with id "t1"/,
+    );
+  });
+
+  it('reports an unknown id instead of throwing, so a handler can 404', () => {
+    const store = createMockStore(seedThings);
+
+    expect(store.update('nope', { name: 'x' })).toBeUndefined();
+    expect(store.remove('nope')).toBe(false);
+  });
+
+  it('merges a patch and keeps the rest of the item', () => {
+    const store = createMockStore(seedThings);
+
+    expect(store.update('t1', { size: 42 })).toEqual({
+      id: 't1',
+      name: 'First',
+      size: 42,
+    });
+    expect(store.get('t1')?.size).toBe(42);
+  });
+
+  it('hands out a fresh array each time, so a caller cannot reorder the store', () => {
+    const store = createMockStore(seedThings);
+    const list = store.list();
+    list.pop();
+    list.reverse();
+
+    expect(store.list()).toHaveLength(2);
+    expect(store.list().map((thing) => thing.id)).toEqual(['t1', 't2']);
+    expect(store.list()).not.toBe(store.list());
+  });
+
+  it('but the elements alias the stored items, like `get`', () => {
+    const store = createMockStore(seedThings);
+    const [first] = store.list();
+
+    expect(first).toBe(store.get('t1'));
+    if (!first) throw new Error('expected the seeded store to be non-empty');
+    first.name = 'Mutated';
+
+    expect(store.get('t1')?.name).toBe('Mutated');
+  });
+
+  it('re-seeds on reset', () => {
+    const store = createMockStore(seedThings);
+
+    store.remove('t2');
+    store.insert({ id: 't3', name: 'Third', size: 3 });
+
+    store.reset();
+
+    expect(store.list()).toEqual(seedThings());
+  });
+
+  it('undoes an in-place mutation when the seed constructs its items', () => {
+    const store = createMockStore(seedThings);
+
+    const stored = store.get('t1');
+    if (stored) stored.name = 'Overwritten';
+    expect(store.get('t1')?.name).toBe('Overwritten');
+
+    store.reset();
+
+    expect(store.get('t1')?.name).toBe('First');
+  });
+
+  it('cannot undo one when the seed returns a shared array', () => {
+    // The documented limit of the reset guarantee: the store holds the seed's
+    // own objects, so a seed that hands back the same ones every call has
+    // nothing to restore from.
+    const shared = [{ id: 't1', name: 'First', size: 1 }];
+    const store = createMockStore(() => shared);
+
+    const stored = store.get('t1');
+    if (stored) stored.name = 'Overwritten';
+    store.reset();
+
+    expect(store.get('t1')?.name).toBe('Overwritten');
+  });
+
+  it('replaces the whole collection', () => {
+    const store = createMockStore(seedThings);
+    store.replaceAll([{ id: 'only', name: 'Only', size: 1 }]);
+
+    expect(store.list()).toEqual([{ id: 'only', name: 'Only', size: 1 }]);
+  });
+
+  it('rejects a duplicate id on replaceAll and on the seed, like insert', () => {
+    const store = createMockStore(seedThings);
+
+    expect(() =>
+      store.replaceAll([
+        { id: 'x', name: 'One', size: 1 },
+        { id: 'x', name: 'Two', size: 2 },
+      ]),
+    ).toThrow(/two items with id "x"/);
+    // The rejected collection is not partially applied.
+    expect(store.list()).toEqual(seedThings());
+
+    expect(() =>
+      createMockStore(() => [
+        { id: 'y', name: 'One', size: 1 },
+        { id: 'y', name: 'Two', size: 2 },
+      ]),
+    ).toThrow(/two items with id "y"/);
+  });
+
+  it('keeps an item in place when updated, and stales an earlier reference', () => {
+    const store = createMockStore(seedThings);
+    const before = store.get('t1');
+
+    store.update('t1', { size: 99 });
+
+    expect(store.list().map((thing) => thing.id)).toEqual(['t1', 't2']);
+    expect(before?.size).toBe(1);
+    expect(store.get('t1')?.size).toBe(99);
+  });
+
+  it('re-keys when a patch carries a new id, in place', () => {
+    const store = createMockStore(seedThings);
+
+    expect(store.update('t1', { id: 'moved' })).toEqual({
+      id: 'moved',
+      name: 'First',
+      size: 1,
+    });
+    expect(store.get('moved')?.name).toBe('First');
+    expect(store.get('t1')).toBeUndefined();
+    expect(store.has('t1')).toBe(false);
+    expect(store.size).toBe(2);
+    // The re-key is not a remove-and-append: the item keeps its position.
+    expect(store.list().map((thing) => thing.id)).toEqual(['moved', 't2']);
+  });
+
+  it('re-keys through an explicit id selector too', () => {
+    const store = createMockStore<{ slug: string; name: string }>(
+      () => [{ slug: 'a', name: 'A' }],
+      { id: (item) => item.slug },
+    );
+
+    store.update('a', { slug: 'b' });
+
+    expect(store.get('b')?.name).toBe('A');
+    expect(store.get('a')).toBeUndefined();
+  });
+
+  it('rejects a re-key onto another existing id, leaving the store as it was', () => {
+    const store = createMockStore(seedThings);
+
+    expect(() => store.update('t1', { id: 't2', size: 9 })).toThrow(
+      /already holds an item with id "t2"/,
+    );
+    expect(store.list()).toEqual(seedThings());
+  });
+
+  it('takes an explicit id selector for items with no `id`', () => {
+    const store = createMockStore<{ slug: string }>(() => [{ slug: 'a' }], {
+      id: (item) => item.slug,
+    });
+
+    expect(store.get('a')).toEqual({ slug: 'a' });
+  });
+
+  it('explains itself when an item has no usable id', () => {
+    expect(() =>
+      createMockStore<{ name: string }>(() => [{ name: 'x' }]),
+    ).toThrow(/need a string or number `id`/);
+  });
+});
+
+describe('createMockStore — through the reset convention', () => {
+  const mock = createMockApi<TestPaths>({ baseUrl: '/api' });
+  const things = createMockStore(seedThings);
+
+  const mocks = setupMocks(
+    [
+      mock.get('/things', ({ response }) => response(200).json(things.list())),
+      mock.post('/things', async ({ request, response }) => {
+        const created = {
+          id: `t${things.size + 1}`,
+          ...(await request.json()),
+        };
+
+        return response(201).json(things.insert(created));
+      }),
+      mock.delete('/things/{id}', ({ params, response }) =>
+        things.remove(params.id)
+          ? response(204).empty()
+          : response(404).json({ message: 'not found' }),
+      ),
+    ],
+    { onReset: [things.reset] },
+  );
+
+  const mockServer = setupMockServer(mocks);
+
+  beforeAll(() => mockServer.listen());
+  afterEach(() => mockServer.reset());
+  afterAll(() => mockServer.close());
+
+  const list = async (): Promise<Thing[]> =>
+    (await (await fetch('http://localhost/api/things')).json()) as Thing[];
+
+  it('a write is visible to a later read in the same test', async () => {
+    const created = await fetch('http://localhost/api/things', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Third', size: 3 }),
+    });
+
+    expect(created.status).toBe(201);
+    expect(await list()).toHaveLength(3);
+  });
+
+  it('and is gone by the next one', async () => {
+    expect(await list()).toEqual(seedThings());
+  });
+
+  it('a delete is undone too', async () => {
+    expect(
+      (await fetch('http://localhost/api/things/t1', { method: 'DELETE' }))
+        .status,
+    ).toBe(204);
+    expect(await list()).toHaveLength(1);
+  });
+
+  it('leaving the seed intact', async () => {
+    expect(await list()).toEqual(seedThings());
+  });
+});

package/src/mock-store.ts

@@ -0,0 +1,180 @@
+/**
+ * The smallest amount of state a mock needs to behave like an API rather than a
+ * fixture dump: a POST that shows up in the following GET. Deliberately not a
+ * database — no queries, no indexes, no relations. A mock that needs those is a
+ * mock standing in for logic the real service owns.
+ */
+
+export type MockStoreOptions<T> = {
+  /**
+   * How an item's identity is read. Defaults to its `id` property, which must be
+   * a string or a number.
+   */
+  id?: (item: T) => string;
+};
+
+/**
+ * Aliasing, since it is observable: `get`, `insert`, and the elements of
+ * `list` are the **stored** objects, so mutating one writes through to the
+ * store — only `list`'s array is a copy. `update` replaces the item with
+ * a merged copy instead, which leaves any reference taken before the update
+ * stale. Read again after an update rather than holding a reference across one.
+ */
+export type MockStore<T> = {
+  /**
+   * Every item, in insertion order. The array is fresh, so sorting, slicing, or
+   * splicing it cannot reorder the store — but its elements are the stored
+   * objects, not copies, so mutating one writes through like `get` does.
+   */
+  list: () => T[];
+  get: (id: string) => T | undefined;
+  has: (id: string) => boolean;
+  readonly size: number;
+  /** Adds an item. Throws on a duplicate id, which is a fixture bug rather than an API condition. */
+  insert: (item: T) => T;
+  /**
+   * Merges `patch` into an existing item, keeping its position. `undefined`
+   * when the id is unknown — a handler turns that into its own 404.
+   *
+   * A patch may carry the id, which moves the item to it; the old id then
+   * misses. Throws if that id is already taken, like `insert`, and leaves the
+   * store untouched when it does.
+   */
+  update: (id: string, patch: Partial<T>) => T | undefined;
+  /** `false` when the id is unknown. */
+  remove: (id: string) => boolean;
+  /** Swaps in a whole collection. Throws if two items share an id, like `insert`. */
+  replaceAll: (items: readonly T[]) => void;
+  /** Re-seeds from the seed function. Pass this to `setupMocks({ onReset })`. */
+  reset: () => void;
+};
+
+function defaultIdOf<T>(item: T): string {
+  const id = (item as { id?: unknown }).id;
+
+  if (typeof id === 'string') return id;
+  if (typeof id === 'number') return String(id);
+
+  throw new Error(
+    'http-client-msw: createMockStore items need a string or number `id`, or an explicit `id` selector',
+  );
+}
+
+/**
+ * An in-memory collection whose `reset` restores the seeded contents.
+ *
+ * The seed is a **function**, called on construction and again on every reset, so
+ * a handler that mutates an item in place cannot corrupt the next test's
+ * starting point. That holds only if the function *constructs* its items — a
+ * seed that returns a shared module-level array hands out the same objects every
+ * time, and a mutation to one of those does survive a reset.
+ *
+ * ```ts
+ * const things = createMockStore(seedThings);
+ *
+ * export const mocks = setupMocks(
+ *   [
+ *     mock.get('/things', ({ response }) => response(200).json(things.list())),
+ *     mock.get('/things/{id}', ({ params, response }) => {
+ *       const thing = things.get(params.id);
+ *
+ *       return thing
+ *         ? response(200).json(thing)
+ *         : response(404).json({ message: 'not found' });
+ *     }),
+ *   ],
+ *   { onReset: [things.reset] },
+ * );
+ * ```
+ */
+export function createMockStore<T>(
+  seed: () => readonly T[],
+  options: MockStoreOptions<T> = {},
+): MockStore<T> {
+  const idOf = options.id ?? defaultIdOf;
+  const items = new Map<string, T>();
+
+  /**
+   * Built into a staging map first, so the duplicate-id check that `insert`
+   * enforces also covers construction and every reset — and so a rejected
+   * collection leaves the store as it was rather than half-cleared.
+   */
+  const replaceAll = (next: readonly T[]): void => {
+    const replacement = new Map<string, T>();
+
+    for (const item of next) {
+      const id = idOf(item);
+      if (replacement.has(id)) {
+        throw new Error(
+          `http-client-msw: createMockStore was given two items with id "${id}"`,
+        );
+      }
+      replacement.set(id, item);
+    }
+
+    items.clear();
+    for (const [id, item] of replacement) items.set(id, item);
+  };
+
+  replaceAll(seed());
+
+  return {
+    list: () => [...items.values()],
+    get: (id) => items.get(id),
+    has: (id) => items.has(id),
+    get size() {
+      return items.size;
+    },
+    insert: (item) => {
+      const id = idOf(item);
+      if (items.has(id)) {
+        throw new Error(
+          `http-client-msw: createMockStore already holds an item with id "${id}"`,
+        );
+      }
+      items.set(id, item);
+
+      return item;
+    },
+    update: (id, patch) => {
+      const existing = items.get(id);
+      if (existing === undefined) return undefined;
+
+      const updated = { ...existing, ...patch };
+      // `Partial<T>` admits the id, so the patch can move the item. Re-derived
+      // rather than assumed, because leaving it under the old key desyncs the
+      // map from the items in it: `get(item.id)` misses and `get(oldId)` hands
+      // back an item that no longer claims that id.
+      const nextId = idOf(updated);
+
+      if (nextId === id) {
+        items.set(id, updated);
+
+        return updated;
+      }
+
+      if (items.has(nextId)) {
+        throw new Error(
+          `http-client-msw: createMockStore already holds an item with id "${nextId}"`,
+        );
+      }
+
+      // Rebuilt in order rather than delete-then-set, which would move the item
+      // to the end: `update` keeps an item's position, and a patched id is
+      // still an update. The collision above throws before anything is
+      // touched, so a rejected patch leaves the store as it was.
+      const entries = [...items];
+
+      items.clear();
+      for (const [key, item] of entries) {
+        if (key === id) items.set(nextId, updated);
+        else items.set(key, item);
+      }
+
+      return updated;
+    },
+    remove: (id) => items.delete(id),
+    replaceAll,
+    reset: () => replaceAll(seed()),
+  };
+}