@schmock/core 1.13.0 → 2.0.1

package/src/interceptor.ts

@@ -0,0 +1,272 @@
+/// <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 =
+    init?.headers ?? (input instanceof Request ? input.headers : undefined);
+  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.toLowerCase()] = value;
+    }
+  } else {
+    for (const key of Object.keys(raw)) {
+      headers[key.toLowerCase()] = (raw as Record<string, string>)[key];
+    }
+  }
+
+  return headers;
+}
+
+/**
+ * Extract body from fetch init, parsing JSON when possible.
+ */
+async function extractBody(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<unknown> {
+  // Per Fetch spec, init.body overrides Request.body when both are present
+  const bodyInit = init?.body ?? (input instanceof Request ? input.body : null);
+  if (bodyInit === null || bodyInit === undefined) return undefined;
+
+  // String body — try to parse as JSON
+  if (typeof bodyInit === "string") {
+    try {
+      return JSON.parse(bodyInit);
+    } catch {
+      return bodyInit;
+    }
+  }
+
+  // URLSearchParams — convert to key/value object
+  if (bodyInit instanceof URLSearchParams) {
+    const result: Record<string, string> = {};
+    bodyInit.forEach((value, key) => {
+      result[key] = value;
+    });
+    return result;
+  }
+
+  // Request with body — clone and read
+  if (input instanceof Request && !init?.body && 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
+    // Enforce segment boundary: /api must not match /apiv2
+    if (baseUrl) {
+      const normalizedBase = baseUrl.endsWith("/")
+        ? baseUrl.slice(0, -1)
+        : baseUrl;
+      const isMatch =
+        path === normalizedBase || path.startsWith(`${normalizedBase}/`);
+      if (!isMatch) {
+        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/parser.property.test.ts

@@ -491,3 +491,104 @@ describe("handle() — fuzz", () => {
     );
   });
 });
+
+// ============================================================
+// Route matching round-trip properties
+// ============================================================
+
+describe("route matching round-trip — property", () => {
+  it("parameterized route: arbitrary param values are extracted correctly", () => {
+    fc.assert(
+      fc.asyncProperty(
+        safeSeg,
+        safeSeg,
+        safeSeg,
+        async (resource, paramA, paramB) => {
+          const mock = schmock();
+          let capturedParams: Record<string, string> = {};
+          mock(`GET /${resource}/:a/:b` as any, (ctx) => {
+            capturedParams = ctx.params;
+            return { ok: true };
+          });
+
+          const response = await mock.handle(
+            "GET",
+            `/${resource}/${paramA}/${paramB}`,
+          );
+          expect(response.status).toBe(200);
+          expect(capturedParams.a).toBe(paramA);
+          expect(capturedParams.b).toBe(paramB);
+        },
+      ),
+      { numRuns: 300 },
+    );
+  });
+
+  it("any valid response format produces a valid Response with status/body/headers", () => {
+    const responseGen = fc.oneof(
+      // Object body
+      fc.record({ key: safeSeg }),
+      // Tuple [status, body]
+      fc.tuple(fc.integer({ min: 100, max: 599 }), fc.record({ v: safeSeg })),
+      // Tuple [status, body, headers]
+      fc.tuple(
+        fc.integer({ min: 100, max: 599 }),
+        fc.record({ v: safeSeg }),
+        fc.constant({}),
+      ),
+      // null/undefined
+      fc.constant(null),
+      fc.constant(undefined),
+    );
+
+    fc.assert(
+      fc.asyncProperty(responseGen, async (genValue) => {
+        const mock = schmock();
+        mock("GET /test", () => genValue);
+
+        const response = await mock.handle("GET", "/test");
+        expect(typeof response.status).toBe("number");
+        expect(response.status).toBeGreaterThanOrEqual(100);
+        expect(response.status).toBeLessThanOrEqual(599);
+        expect(response).toHaveProperty("headers");
+        expect(typeof response.headers).toBe("object");
+      }),
+      { numRuns: 300 },
+    );
+  });
+
+  it("header keys are always lowercased after extractHeaders in interceptor", () => {
+    const headerKey = fc
+      .stringMatching(/^[A-Za-z][A-Za-z0-9-]{0,20}$/)
+      .filter((k) => k.length > 0);
+    const headerVal = safeSeg;
+
+    fc.assert(
+      fc.asyncProperty(headerKey, headerVal, async (key, val) => {
+        const mock = schmock();
+        let capturedHeaders: Record<string, string> = {};
+        mock("GET /hdr", (ctx) => {
+          capturedHeaders = ctx.headers;
+          return { ok: true };
+        });
+        const handle = mock.intercept();
+
+        try {
+          await fetch("http://localhost/hdr", {
+            headers: { [key]: val },
+          });
+
+          // All header keys should be lowercase
+          for (const hdrKey of Object.keys(capturedHeaders)) {
+            expect(hdrKey).toBe(hdrKey.toLowerCase());
+          }
+          // The value should be preserved
+          expect(capturedHeaders[key.toLowerCase()]).toBe(val);
+        } finally {
+          handle.restore();
+        }
+      }),
+      { numRuns: 200 },
+    );
+  });
+});

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`);
       }
 

package/src/response-parsing.test.ts

@@ -225,6 +225,80 @@ describe("response parsing", () => {
     });
   });
 
+  describe("status code boundaries", () => {
+    it("status code 100 (lower boundary) is accepted as tuple", async () => {
+      const mock = schmock();
+      mock("GET /continue", () => [100, "Continue"]);
+
+      const response = await mock.handle("GET", "/continue");
+      expect(response.status).toBe(100);
+      expect(response.body).toBe("Continue");
+    });
+
+    it("status code 599 (upper boundary) is accepted as tuple", async () => {
+      const mock = schmock();
+      mock("GET /custom", () => [599, { message: "custom status" }]);
+
+      const response = await mock.handle("GET", "/custom");
+      expect(response.status).toBe(599);
+      expect(response.body).toEqual({ message: "custom status" });
+    });
+
+    it("float status like 200.5 is accepted as tuple (number check)", async () => {
+      const mock = schmock();
+      mock("GET /float", () => [200.5, { ok: true }]);
+
+      const response = await mock.handle("GET", "/float");
+      // isStatusTuple checks typeof === 'number' and 100 <= n <= 599
+      // 200.5 passes both checks, so it's treated as a tuple
+      expect(response.status).toBe(200.5);
+      expect(response.body).toEqual({ ok: true });
+    });
+
+    it("array [201, null, undefined] — tuple with undefined headers defaults to empty", async () => {
+      const mock = schmock();
+      mock("GET /null-headers", () => [201, null, undefined] as any);
+
+      const response = await mock.handle("GET", "/null-headers");
+      // isStatusTuple: length 3, first element 201 (number, 100-599) -> true
+      // destructure: [status=201, body=null, headers=undefined]
+      // headers defaults to {} via `headers = {}`
+      expect(response.status).toBe(201);
+      expect(response.body).toBeUndefined(); // null body becomes undefined
+      expect(response.headers).toEqual({});
+    });
+
+    it("non-tuple array [1, 2, 3, 4] with length > 3 treated as body", async () => {
+      const mock = schmock();
+      mock("GET /long-array", () => [1, 2, 3, 4] as any);
+
+      const response = await mock.handle("GET", "/long-array");
+      // isStatusTuple requires length 2 or 3, so length 4 => not a tuple => body
+      expect(response.status).toBe(200);
+      expect(response.body).toEqual([1, 2, 3, 4]);
+    });
+
+    it("status 99 (below 100) is NOT treated as a tuple", async () => {
+      const mock = schmock();
+      mock("GET /below-range", () => [99, { data: true }]);
+
+      const response = await mock.handle("GET", "/below-range");
+      // isStatusTuple requires value[0] >= 100, so 99 fails => treated as body
+      expect(response.status).toBe(200);
+      expect(response.body).toEqual([99, { data: true }]);
+    });
+
+    it("status 600 (above 599) is NOT treated as a tuple", async () => {
+      const mock = schmock();
+      mock("GET /above-range", () => [600, { data: true }]);
+
+      const response = await mock.handle("GET", "/above-range");
+      // isStatusTuple requires value[0] <= 599, so 600 fails => treated as body
+      expect(response.status).toBe(200);
+      expect(response.body).toEqual([600, { data: true }]);
+    });
+  });
+
   describe("edge cases", () => {
     it("handles response with circular references gracefully", async () => {
       const mock = schmock();

package/src/server.test.ts

@@ -113,4 +113,53 @@ describe("Standalone Server", () => {
     mock.close();
     expect(() => mock.close()).not.toThrow();
   });
+
+  it("generator that throws synchronously returns 500", async () => {
+    mock = schmock();
+    mock("GET /boom", () => {
+      throw new Error("sync kaboom");
+    });
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/boom`);
+    expect(res.status).toBe(500);
+    const body = await res.json();
+    expect(body.error).toBe("sync kaboom");
+  });
+
+  it("generator that returns rejected Promise returns 500", async () => {
+    mock = schmock();
+    mock("GET /reject", async () => {
+      throw new Error("async rejection");
+    });
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/reject`);
+    expect(res.status).toBe(500);
+    const body = await res.json();
+    expect(body.error).toBe("async rejection");
+  });
+
+  it("close terminates keep-alive connections immediately", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    const info = await mock.listen(0);
+
+    // Make a keep-alive request to establish a persistent connection
+    const res = await fetch(`http://127.0.0.1:${info.port}/test`, {
+      headers: { connection: "keep-alive" },
+    });
+    expect(res.status).toBe(200);
+
+    // Close the server — should terminate all connections
+    mock.close();
+
+    // Subsequent request should fail immediately (not hang on keep-alive)
+    try {
+      await fetch(`http://127.0.0.1:${info.port}/test`);
+      expect.unreachable("Should have thrown");
+    } catch {
+      // Expected: connection refused
+    }
+  });
 });

package/src/steps/async-support.steps.ts

@@ -64,41 +64,6 @@ describeFeature(feature, ({ Scenario }) => {
     });
   });
 
-  Scenario("Multiple async generators in different routes", ({ Given, When, Then, And }) => {
-    Given("I create a mock with async routes for posts and comments", () => {
-      mock = schmock();
-      mock("GET /async-posts", async () => {
-        await new Promise(resolve => setTimeout(resolve, 5));
-        return [{ id: 1, title: "First Post" }];
-      });
-      mock("GET /async-comments", async () => {
-        await new Promise(resolve => setTimeout(resolve, 8));
-        return [{ id: 1, comment: "Great post!" }];
-      });
-    });
-
-    When("I make concurrent requests to {string} and {string}", async (_, path1: string, path2: string) => {
-      const [posts, comments] = await Promise.all([
-        mock.handle("GET", path1),
-        mock.handle("GET", path2),
-      ]);
-      responses = [posts, comments];
-    });
-
-    Then("both responses should be returned successfully", () => {
-      expect(responses[0].status).toBe(200);
-      expect(responses[1].status).toBe(200);
-    });
-
-    And("the posts response should contain {string}", (_, text: string) => {
-      expect(JSON.stringify(responses[0].body)).toContain(text);
-    });
-
-    And("the comments response should contain {string}", (_, text: string) => {
-      expect(JSON.stringify(responses[1].body)).toContain(text);
-    });
-  });
-
   Scenario("Async plugin processing", ({ Given, When, Then, And }) => {
     Given("I create a mock with an async processing plugin at {string}", (_, route: string) => {
       const [method, path] = route.split(" ");

package/src/steps/basic-usage.steps.ts

@@ -110,90 +110,6 @@ describeFeature(feature, ({ Scenario }) => {
     });
   });
 
-  Scenario("Undefined response", ({ Given, When, Then, And }) => {
-    Given("I create a mock returning undefined at {string}", (_, route: string) => {
-      const [method, path] = route.split(" ");
-      mock = schmock();
-      mock(`${method} ${path}` as Schmock.RouteKey, undefined);
-    });
-
-    When("I request {string}", async (_, request: string) => {
-      const [method, path] = request.split(" ");
-      response = await mock.handle(method as any, path);
-    });
-
-    Then("I should receive empty response", () => {
-      expect(response.body).toBeUndefined();
-    });
-
-    And("the status should be {int}", (_, status: number) => {
-      expect(response.status).toBe(status);
-    });
-  });
-
-  Scenario("Empty string response", ({ Given, When, Then, And }) => {
-    Given("I create a mock returning empty string at {string}", (_, route: string) => {
-      const [method, path] = route.split(" ");
-      mock = schmock();
-      mock(`${method} ${path}` as Schmock.RouteKey, "");
-    });
-
-    When("I request {string}", async (_, request: string) => {
-      const [method, path] = request.split(" ");
-      response = await mock.handle(method as any, path);
-    });
-
-    Then("I should receive text {string}", (_, expectedText: string) => {
-      expect(response.body).toBe(expectedText);
-    });
-
-    And("the content-type should be {string}", (_, contentType: string) => {
-      expect(response.headers?.["content-type"]).toBe(contentType);
-    });
-  });
-
-  Scenario("Number response", ({ Given, When, Then, And }) => {
-    Given("I create a mock returning number {int} at {string}", (_, num: number, route: string) => {
-      const [method, path] = route.split(" ");
-      mock = schmock();
-      mock(`${method} ${path}` as Schmock.RouteKey, num);
-    });
-
-    When("I request {string}", async (_, request: string) => {
-      const [method, path] = request.split(" ");
-      response = await mock.handle(method as any, path);
-    });
-
-    Then("I should receive text {string}", (_, expectedText: string) => {
-      expect(response.body).toBe(expectedText);
-    });
-
-    And("the content-type should be {string}", (_, contentType: string) => {
-      expect(response.headers?.["content-type"]).toBe(contentType);
-    });
-  });
-
-  Scenario("Boolean response", ({ Given, When, Then, And }) => {
-    Given("I create a mock returning boolean true at {string}", (_, route: string) => {
-      const [method, path] = route.split(" ");
-      mock = schmock();
-      mock(`${method} ${path}` as Schmock.RouteKey, true);
-    });
-
-    When("I request {string}", async (_, request: string) => {
-      const [method, path] = request.split(" ");
-      response = await mock.handle(method as any, path);
-    });
-
-    Then("I should receive text {string}", (_, expectedText: string) => {
-      expect(response.body).toBe(expectedText);
-    });
-
-    And("the content-type should be {string}", (_, contentType: string) => {
-      expect(response.headers?.["content-type"]).toBe(contentType);
-    });
-  });
-
   Scenario("Function returning string", ({ Given, When, Then }) => {
     Given("I create a mock with a string generator at {string}", (_, route: string) => {
       const [method, path] = route.split(" ");