@schmock/core 1.13.0 → 2.0.0

package/src/helpers.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+import {
+  badRequest,
+  created,
+  forbidden,
+  noContent,
+  notFound,
+  paginate,
+  serverError,
+  unauthorized,
+} from "./helpers.js";
+
+describe("notFound", () => {
+  it("returns 404 with default message", () => {
+    expect(notFound()).toEqual([404, { message: "Not Found" }]);
+  });
+  it("returns 404 with custom string message", () => {
+    expect(notFound("User not found")).toEqual([
+      404,
+      { message: "User not found" },
+    ]);
+  });
+  it("returns 404 with custom object", () => {
+    expect(notFound({ code: "NOT_FOUND", detail: "gone" })).toEqual([
+      404,
+      { code: "NOT_FOUND", detail: "gone" },
+    ]);
+  });
+});
+
+describe("badRequest", () => {
+  it("returns 400 with default message", () => {
+    expect(badRequest()).toEqual([400, { message: "Bad Request" }]);
+  });
+  it("returns 400 with custom string", () => {
+    expect(badRequest("Invalid email")).toEqual([
+      400,
+      { message: "Invalid email" },
+    ]);
+  });
+});
+
+describe("unauthorized", () => {
+  it("returns 401 with default message", () => {
+    expect(unauthorized()).toEqual([401, { message: "Unauthorized" }]);
+  });
+});
+
+describe("forbidden", () => {
+  it("returns 403 with default message", () => {
+    expect(forbidden()).toEqual([403, { message: "Forbidden" }]);
+  });
+});
+
+describe("serverError", () => {
+  it("returns 500 with default message", () => {
+    expect(serverError()).toEqual([500, { message: "Internal Server Error" }]);
+  });
+});
+
+describe("created", () => {
+  it("returns 201 with body", () => {
+    expect(created({ id: 1, name: "John" })).toEqual([
+      201,
+      { id: 1, name: "John" },
+    ]);
+  });
+});
+
+describe("noContent", () => {
+  it("returns 204 with null body", () => {
+    expect(noContent()).toEqual([204, null]);
+  });
+});
+
+describe("paginate", () => {
+  const items = [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }];
+
+  it("returns first page with default pageSize", () => {
+    const result = paginate(items);
+    expect(result).toEqual({
+      data: items,
+      page: 1,
+      pageSize: 10,
+      total: 5,
+      totalPages: 1,
+    });
+  });
+
+  it("paginates correctly with custom options", () => {
+    const result = paginate(items, { page: 2, pageSize: 2 });
+    expect(result).toEqual({
+      data: [{ id: 3 }, { id: 4 }],
+      page: 2,
+      pageSize: 2,
+      total: 5,
+      totalPages: 3,
+    });
+  });
+
+  it("returns empty data for page beyond range", () => {
+    const result = paginate(items, { page: 10, pageSize: 2 });
+    expect(result.data).toEqual([]);
+    expect(result.total).toBe(5);
+  });
+});

package/src/helpers.ts

@@ -0,0 +1,58 @@
+/// <reference path="../schmock.d.ts" />
+
+export function notFound(
+  message: string | object = "Not Found",
+): [number, object] {
+  const body = typeof message === "string" ? { message } : message;
+  return [404, body];
+}
+
+export function badRequest(
+  message: string | object = "Bad Request",
+): [number, object] {
+  const body = typeof message === "string" ? { message } : message;
+  return [400, body];
+}
+
+export function unauthorized(
+  message: string | object = "Unauthorized",
+): [number, object] {
+  const body = typeof message === "string" ? { message } : message;
+  return [401, body];
+}
+
+export function forbidden(
+  message: string | object = "Forbidden",
+): [number, object] {
+  const body = typeof message === "string" ? { message } : message;
+  return [403, body];
+}
+
+export function serverError(
+  message: string | object = "Internal Server Error",
+): [number, object] {
+  const body = typeof message === "string" ? { message } : message;
+  return [500, body];
+}
+
+export function created(body: object): [number, object] {
+  return [201, body];
+}
+
+export function noContent(): [number, null] {
+  return [204, null];
+}
+
+export function paginate<T>(
+  items: T[],
+  options: Schmock.PaginateOptions = {},
+): Schmock.PaginatedResponse<T> {
+  const page = options.page || 1;
+  const pageSize = options.pageSize || 10;
+  const total = items.length;
+  const totalPages = Math.ceil(total / pageSize);
+  const start = (page - 1) * pageSize;
+  const end = start + pageSize;
+  const data = items.slice(start, end);
+  return { data, page, pageSize, total, totalPages };
+}

package/src/index.ts

@@ -70,6 +70,8 @@ export function schmock(
       getState: instance.getState.bind(instance),
       listen: instance.listen.bind(instance),
       close: instance.close.bind(instance),
+      intercept: (options?: Schmock.InterceptOptions) =>
+        instance.intercept(options),
     },
   );
 
@@ -82,6 +84,7 @@ export function schmock(
 export {
   HTTP_METHODS,
   isHttpMethod,
+  isRouteNotFound,
   isStatusTuple,
   ROUTE_NOT_FOUND_CODE,
   toHttpMethod,
@@ -99,6 +102,17 @@ export {
   SchemaValidationError,
   SchmockError,
 } from "./errors.js";
+// Re-export response helpers
+export {
+  badRequest,
+  created,
+  forbidden,
+  noContent,
+  notFound,
+  paginate,
+  serverError,
+  unauthorized,
+} from "./helpers.js";
 // Re-export HTTP server helpers
 export {
   collectBody,
@@ -107,12 +121,19 @@ export {
   writeSchmockResponse,
 } from "./http-helpers.js";
 // Re-export types
+// Re-export interceptor
+export { createFetchInterceptor } from "./interceptor.js";
+// Re-export types
 export type {
+  AdapterRequest,
+  AdapterResponse,
   CallableMockInstance,
   Generator,
   GeneratorFunction,
   GlobalConfig,
   HttpMethod,
+  InterceptHandle,
+  InterceptOptions,
   Plugin,
   PluginContext,
   PluginResult,

package/src/interceptor.test.ts

@@ -0,0 +1,160 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { schmock } from "./index.js";
+
+describe("mock.intercept()", () => {
+  let originalFetch: typeof globalThis.fetch;
+  let mock: Schmock.CallableMockInstance;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn().mockResolvedValue(new Response("real backend"));
+    mock = schmock();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("intercepts a matched fetch request and returns mocked response", async () => {
+    mock("GET /api/users", [{ id: 1, name: "Alice" }]);
+    const handle = mock.intercept();
+
+    const res = await fetch("http://localhost/api/users");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ id: 1, name: "Alice" }]);
+
+    handle.restore();
+  });
+
+  it("passes through unmatched routes when passthrough is true", async () => {
+    mock("GET /api/users", [{ id: 1 }]);
+    // Save reference to the vi.fn() mock that the interceptor will call on passthrough
+    const mockFetch = globalThis.fetch as ReturnType<typeof vi.fn>;
+    const handle = mock.intercept({ passthrough: true });
+
+    await fetch("http://localhost/api/other");
+    // The interceptor saves the vi.fn() as its original and calls it on passthrough
+    expect(mockFetch).toHaveBeenCalled();
+    handle.restore();
+  });
+
+  it("returns 404 when passthrough is disabled and route not found", async () => {
+    mock("GET /api/users", [{ id: 1 }]);
+    const handle = mock.intercept({ passthrough: false });
+
+    const res = await fetch("http://localhost/api/other");
+    expect(res.status).toBe(404);
+
+    handle.restore();
+  });
+
+  it("restores original fetch", () => {
+    const savedFetch = globalThis.fetch;
+    const handle = mock.intercept();
+
+    expect(globalThis.fetch).not.toBe(savedFetch);
+    handle.restore();
+    expect(globalThis.fetch).toBe(savedFetch);
+  });
+
+  it("reports active status", () => {
+    const handle = mock.intercept();
+    expect(handle.active).toBe(true);
+
+    handle.restore();
+    expect(handle.active).toBe(false);
+  });
+
+  it("filters by baseUrl", async () => {
+    mock("GET /api/users", [{ id: 1 }]);
+    const savedFetch = globalThis.fetch;
+    const handle = mock.intercept({ baseUrl: "/api" });
+
+    await fetch("http://localhost/other/path");
+    // Should have called the saved fetch (passthrough for non-matching baseUrl)
+    expect(savedFetch).toHaveBeenCalled();
+
+    handle.restore();
+  });
+
+  it("throws when intercepting twice", () => {
+    const handle = mock.intercept();
+    expect(() => mock.intercept()).toThrow(/already intercepting/i);
+    handle.restore();
+  });
+
+  it("applies beforeRequest hook", async () => {
+    mock("GET /api/users", ({ headers }) => [
+      200,
+      { token: headers["x-token"] },
+    ]);
+    const handle = mock.intercept({
+      beforeRequest: (req) => ({
+        ...req,
+        headers: { ...req.headers, "x-token": "injected" },
+      }),
+    });
+
+    const res = await fetch("http://localhost/api/users");
+    expect(await res.json()).toEqual({ token: "injected" });
+
+    handle.restore();
+  });
+
+  it("applies beforeResponse hook", async () => {
+    mock("GET /api/users", [{ id: 1 }]);
+    const handle = mock.intercept({
+      beforeResponse: (resp) => ({
+        ...resp,
+        headers: { ...resp.headers, "x-mock": "true" },
+      }),
+    });
+
+    const res = await fetch("http://localhost/api/users");
+    expect(res.headers.get("x-mock")).toBe("true");
+
+    handle.restore();
+  });
+
+  it("handles relative URLs", async () => {
+    mock("GET /api/users", [{ id: 1 }]);
+    const handle = mock.intercept();
+
+    const res = await fetch("/api/users");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ id: 1 }]);
+
+    handle.restore();
+  });
+
+  it("applies errorFormatter when beforeRequest throws", async () => {
+    mock("GET /api/users", [{ id: 1 }]);
+    const handle = mock.intercept({
+      beforeRequest: () => {
+        throw new Error("hook failed");
+      },
+      errorFormatter: (err) => ({ custom: err.message }),
+    });
+
+    const res = await fetch("http://localhost/api/users");
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({ custom: "hook failed" });
+
+    handle.restore();
+  });
+
+  it("parses JSON body from fetch init", async () => {
+    mock("POST /api/users", ({ body }) => [201, body]);
+    const handle = mock.intercept();
+
+    const res = await fetch("http://localhost/api/users", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "Alice" }),
+    });
+    expect(res.status).toBe(201);
+    expect(await res.json()).toEqual({ name: "Alice" });
+
+    handle.restore();
+  });
+});

package/src/interceptor.ts

@@ -0,0 +1,252 @@
+/// <reference path="../schmock.d.ts" />
+
+import { isRouteNotFound, toHttpMethod } from "./constants.js";
+
+/**
+ * Extract pathname from a URL string, handling both absolute and relative URLs.
+ */
+function extractPathname(url: string): string {
+  const queryStart = url.indexOf("?");
+  const urlWithoutQuery = queryStart === -1 ? url : url.slice(0, queryStart);
+
+  if (urlWithoutQuery.includes("://")) {
+    try {
+      return new URL(urlWithoutQuery).pathname;
+    } catch {
+      // Fall through to simple extraction
+    }
+  }
+
+  if (!urlWithoutQuery.startsWith("/")) {
+    return `/${urlWithoutQuery}`;
+  }
+
+  return urlWithoutQuery;
+}
+
+/**
+ * Extract query parameters from a URL string.
+ */
+function extractQuery(url: string): Record<string, string> {
+  const queryStart = url.indexOf("?");
+  if (queryStart === -1) return {};
+
+  const params = new URLSearchParams(url.slice(queryStart + 1));
+  const result: Record<string, string> = {};
+  params.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+}
+
+/**
+ * Extract headers from fetch init or Request object.
+ */
+function extractHeaders(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  const raw = input instanceof Request ? input.headers : init?.headers;
+  if (!raw) return headers;
+
+  if (raw instanceof Headers) {
+    raw.forEach((value, key) => {
+      headers[key] = value;
+    });
+  } else if (Array.isArray(raw)) {
+    for (const [key, value] of raw) {
+      headers[key] = value;
+    }
+  } else {
+    Object.assign(headers, raw);
+  }
+
+  return headers;
+}
+
+/**
+ * Extract body from fetch init, parsing JSON when possible.
+ */
+async function extractBody(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<unknown> {
+  const rawBody = input instanceof Request ? input.body : init?.body;
+  if (rawBody === null || rawBody === undefined) return undefined;
+
+  // String body — try to parse as JSON
+  const bodyInit = init?.body;
+  if (typeof bodyInit === "string") {
+    try {
+      return JSON.parse(bodyInit);
+    } catch {
+      return bodyInit;
+    }
+  }
+
+  // Request with body — clone and read
+  if (input instanceof Request && input.body) {
+    try {
+      return await input.clone().json();
+    } catch {
+      try {
+        return await input.clone().text();
+      } catch {
+        return undefined;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Create a fetch interceptor that routes requests through mock.handle().
+ */
+export function createFetchInterceptor(
+  handle: (
+    method: Schmock.HttpMethod,
+    path: string,
+    requestOptions?: Schmock.RequestOptions,
+  ) => Promise<Schmock.Response>,
+  options: Schmock.InterceptOptions = {},
+): Schmock.InterceptHandle {
+  const {
+    baseUrl,
+    passthrough = true,
+    beforeRequest,
+    beforeResponse,
+    errorFormatter,
+  } = options;
+
+  const originalFetch = globalThis.fetch;
+  let active = true;
+
+  globalThis.fetch = async (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    // Resolve the URL string
+    const urlString =
+      input instanceof Request
+        ? input.url
+        : input instanceof URL
+          ? input.href
+          : input;
+
+    const path = extractPathname(urlString);
+
+    // BaseUrl filter — non-matching requests go straight to real fetch
+    if (baseUrl && !path.startsWith(baseUrl)) {
+      return originalFetch(input, init);
+    }
+
+    // Build adapter request
+    const method =
+      input instanceof Request ? input.method : (init?.method ?? "GET");
+    const headers = extractHeaders(input, init);
+    const query = extractQuery(urlString);
+    const body = await extractBody(input, init);
+
+    let adapterRequest: Schmock.AdapterRequest = {
+      method,
+      path,
+      headers,
+      body,
+      query,
+    };
+
+    try {
+      // Apply beforeRequest hook
+      if (beforeRequest) {
+        const modified = await beforeRequest(adapterRequest);
+        if (modified) {
+          adapterRequest = modified;
+        }
+      }
+
+      const schmockResponse = await handle(
+        toHttpMethod(adapterRequest.method),
+        adapterRequest.path,
+        {
+          headers: adapterRequest.headers,
+          body: adapterRequest.body,
+          query: adapterRequest.query,
+        },
+      );
+
+      // Route not found — passthrough or 404
+      if (isRouteNotFound(schmockResponse)) {
+        if (passthrough) {
+          return originalFetch(input, init);
+        }
+        return new Response(
+          JSON.stringify({
+            error: "No matching mock route found",
+            code: "ROUTE_NOT_FOUND",
+          }),
+          {
+            status: 404,
+            headers: { "content-type": "application/json" },
+          },
+        );
+      }
+
+      // Apply beforeResponse hook
+      let response: Schmock.AdapterResponse = schmockResponse;
+      if (beforeResponse) {
+        const modified = await beforeResponse(response, adapterRequest);
+        if (modified) {
+          response = modified;
+        }
+      }
+
+      // Build fetch Response
+      const responseHeaders = new Headers(response.headers);
+      if (
+        !responseHeaders.has("content-type") &&
+        response.body !== null &&
+        response.body !== undefined
+      ) {
+        responseHeaders.set("content-type", "application/json");
+      }
+
+      const responseBody =
+        response.body === null || response.body === undefined
+          ? null
+          : typeof response.body === "string"
+            ? response.body
+            : JSON.stringify(response.body);
+
+      return new Response(responseBody, {
+        status: response.status,
+        headers: responseHeaders,
+      });
+    } catch (error) {
+      if (errorFormatter) {
+        const formatted = errorFormatter(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+        return new Response(JSON.stringify(formatted), {
+          status: 500,
+          headers: { "content-type": "application/json" },
+        });
+      }
+      throw error;
+    }
+  };
+
+  return {
+    restore() {
+      if (active) {
+        globalThis.fetch = originalFetch;
+        active = false;
+      }
+    },
+    get active() {
+      return active;
+    },
+  };
+}

package/src/plugin-pipeline.ts

@@ -30,7 +30,7 @@ export async function runPluginPipeline(
     try {
       const result = await plugin.process(currentContext, response);
 
-      if (!result || !result.context) {
+      if (!result?.context) {
         throw new Error(`Plugin ${plugin.name} didn't return valid result`);
       }