@schmock/core 1.0.0

package/src/namespace.test.ts

@@ -0,0 +1,273 @@
+import { describe, expect, it } from "vitest";
+import { schmock } from "./index";
+
+describe("namespace functionality", () => {
+  describe("basic namespace behavior", () => {
+    it("applies namespace to all routes", async () => {
+      const mock = schmock({ namespace: "/api" });
+      mock("GET /users", "users");
+      mock("POST /users", "create-user");
+
+      const getResponse = await mock.handle("GET", "/api/users");
+      const postResponse = await mock.handle("POST", "/api/users");
+
+      expect(getResponse.body).toBe("users");
+      expect(postResponse.body).toBe("create-user");
+    });
+
+    it("returns 404 for requests without namespace prefix", async () => {
+      const mock = schmock({ namespace: "/api" });
+      mock("GET /users", "users");
+
+      const response = await mock.handle("GET", "/users");
+
+      expect(response.status).toBe(404);
+      expect(response.body.error).toContain("Route not found: GET /users");
+    });
+
+    it("handles nested namespaces", async () => {
+      const mock = schmock({ namespace: "/api/v1" });
+      mock("GET /users", "v1-users");
+
+      const response = await mock.handle("GET", "/api/v1/users");
+
+      expect(response.body).toBe("v1-users");
+    });
+
+    it("works with root namespace", async () => {
+      const mock = schmock({ namespace: "/" });
+      mock("GET /users", "users");
+
+      const response = await mock.handle("GET", "/users");
+
+      expect(response.body).toBe("users");
+    });
+  });
+
+  describe("namespace with parameters", () => {
+    it("works with parameterized routes under namespace", async () => {
+      const mock = schmock({ namespace: "/api" });
+      mock("GET /users/:id", ({ params }) => ({ userId: params.id }));
+
+      const response = await mock.handle("GET", "/api/users/123");
+
+      expect(response.body).toEqual({ userId: "123" });
+    });
+
+    it("extracts parameters correctly after namespace removal", async () => {
+      const mock = schmock({ namespace: "/api/v1" });
+      mock("GET /users/:userId/posts/:postId", ({ params, path }) => ({
+        params,
+        processedPath: path,
+      }));
+
+      const response = await mock.handle("GET", "/api/v1/users/456/posts/789");
+
+      expect(response.body).toEqual({
+        params: { userId: "456", postId: "789" },
+        processedPath: "/users/456/posts/789",
+      });
+    });
+
+    it("passes correct path to context after namespace stripping", async () => {
+      const mock = schmock({ namespace: "/api" });
+      mock("GET /test/:param", ({ path, params }) => ({
+        contextPath: path,
+        params,
+      }));
+
+      const response = await mock.handle("GET", "/api/test/value");
+
+      expect(response.body).toEqual({
+        contextPath: "/test/value",
+        params: { param: "value" },
+      });
+    });
+  });
+
+  describe("namespace edge cases", () => {
+    it("handles namespace with trailing slash", async () => {
+      const mock = schmock({ namespace: "/api/" });
+      mock("GET /users", "users");
+
+      // Should work with or without the trailing slash in the request
+      const response1 = await mock.handle("GET", "/api/users");
+      const response2 = await mock.handle("GET", "/api//users");
+
+      expect(response1.body).toBe("users");
+      // This might not match depending on implementation
+      expect(response2.status).toBe(404);
+    });
+
+    it("handles empty namespace", async () => {
+      const mock = schmock({ namespace: "" });
+      mock("GET /users", "users");
+
+      const response = await mock.handle("GET", "/users");
+
+      expect(response.body).toBe("users");
+    });
+
+    it("handles namespace without leading slash", async () => {
+      const mock = schmock({ namespace: "api" });
+      mock("GET /users", "users");
+
+      const response = await mock.handle("GET", "api/users");
+
+      expect(response.body).toBe("users");
+    });
+
+    it("rejects requests that partially match namespace", async () => {
+      const mock = schmock({ namespace: "/api" });
+      mock("GET /users", "users");
+
+      const response1 = await mock.handle("GET", "/ap/users");
+      const response2 = await mock.handle("GET", "/apiextra/users");
+
+      expect(response1.status).toBe(404);
+      expect(response2.status).toBe(404);
+    });
+
+    it("handles very long namespaces", async () => {
+      const longNamespace =
+        "/api/v1/internal/microservice/health/monitoring/endpoints";
+      const mock = schmock({ namespace: longNamespace });
+      mock("GET /status", "healthy");
+
+      const response = await mock.handle("GET", `${longNamespace}/status`);
+
+      expect(response.body).toBe("healthy");
+    });
+  });
+
+  describe("namespace without routes", () => {
+    it("returns 404 when no routes defined", async () => {
+      const mock = schmock({ namespace: "/api" });
+
+      const response = await mock.handle("GET", "/api/anything");
+
+      expect(response.status).toBe(404);
+    });
+
+    it("returns 404 for namespace root when no root route", async () => {
+      const mock = schmock({ namespace: "/api" });
+      mock("GET /users", "users");
+
+      const response = await mock.handle("GET", "/api");
+
+      expect(response.status).toBe(404);
+    });
+
+    it("supports root route under namespace", async () => {
+      const mock = schmock({ namespace: "/api" });
+      mock("GET /", "api-root");
+
+      const response = await mock.handle("GET", "/api/");
+
+      expect(response.body).toBe("api-root");
+    });
+  });
+
+  describe("namespace with global state", () => {
+    it("maintains global state across namespaced routes", async () => {
+      const mock = schmock({
+        namespace: "/api",
+        state: { counter: 0 },
+      });
+
+      mock("POST /increment", ({ state }) => {
+        state.counter++;
+        return { counter: state.counter };
+      });
+
+      mock("GET /count", ({ state }) => ({ counter: state.counter }));
+
+      await mock.handle("POST", "/api/increment");
+      await mock.handle("POST", "/api/increment");
+      const response = await mock.handle("GET", "/api/count");
+
+      expect(response.body).toEqual({ counter: 2 });
+    });
+  });
+
+  describe("namespace with plugins", () => {
+    it("works correctly with plugin pipeline", async () => {
+      const mock = schmock({ namespace: "/api" });
+
+      const plugin = {
+        name: "namespace-plugin",
+        process: (ctx: any, res: any) => {
+          return {
+            context: ctx,
+            response: {
+              ...res,
+              namespacedPath: ctx.path,
+            },
+          };
+        },
+      };
+
+      mock("GET /users", { users: [] }).pipe(plugin);
+
+      const response = await mock.handle("GET", "/api/users");
+
+      expect(response.body).toEqual({
+        users: [],
+        namespacedPath: "/users", // Should be the path after namespace removal
+      });
+    });
+  });
+
+  describe("special characters in namespace", () => {
+    it("handles namespace with special characters", async () => {
+      const mock = schmock({ namespace: "/api-v1.2" });
+      mock("GET /users", "users");
+
+      const response = await mock.handle("GET", "/api-v1.2/users");
+
+      expect(response.body).toBe("users");
+    });
+
+    it("handles namespace with underscores", async () => {
+      const mock = schmock({ namespace: "/my_api" });
+      mock("GET /test", "test");
+
+      const response = await mock.handle("GET", "/my_api/test");
+
+      expect(response.body).toBe("test");
+    });
+
+    it("handles namespace with numbers", async () => {
+      const mock = schmock({ namespace: "/api2" });
+      mock("GET /version", "v2");
+
+      const response = await mock.handle("GET", "/api2/version");
+
+      expect(response.body).toBe("v2");
+    });
+  });
+
+  describe("namespace error messages", () => {
+    it("provides clear error message for namespace mismatch", async () => {
+      const mock = schmock({ namespace: "/api/v1" });
+      mock("GET /users", "users");
+
+      const response = await mock.handle("GET", "/api/v2/users");
+
+      expect(response.status).toBe(404);
+      expect(response.body.error).toContain(
+        "Route not found: GET /api/v2/users",
+      );
+      expect(response.body.code).toBe("ROUTE_NOT_FOUND");
+    });
+
+    it("includes original requested path in error", async () => {
+      const mock = schmock({ namespace: "/api" });
+      mock("GET /users", "users");
+
+      const response = await mock.handle("GET", "/wrong/path");
+
+      expect(response.body.error).toContain("/wrong/path");
+    });
+  });
+});

package/src/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAuC3D"}

package/src/parser.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import { parseRouteKey } from "./parser";
+
+describe("parseRouteKey", () => {
+  describe("valid route keys", () => {
+    it("parses simple GET route", () => {
+      const result = parseRouteKey("GET /users");
+      expect(result).toEqual({
+        method: "GET",
+        path: "/users",
+        pattern: expect.any(RegExp),
+        params: [],
+      });
+    });
+
+    it("parses route with single parameter", () => {
+      const result = parseRouteKey("GET /users/:id");
+      expect(result).toEqual({
+        method: "GET",
+        path: "/users/:id",
+        pattern: expect.any(RegExp),
+        params: ["id"],
+      });
+    });
+
+    it("parses route with multiple parameters", () => {
+      const result = parseRouteKey(
+        "DELETE /api/posts/:postId/comments/:commentId",
+      );
+      expect(result).toEqual({
+        method: "DELETE",
+        path: "/api/posts/:postId/comments/:commentId",
+        pattern: expect.any(RegExp),
+        params: ["postId", "commentId"],
+      });
+    });
+
+    it("supports all HTTP methods", () => {
+      const methods = [
+        "GET",
+        "POST",
+        "PUT",
+        "DELETE",
+        "PATCH",
+        "HEAD",
+        "OPTIONS",
+      ] as const;
+
+      for (const method of methods) {
+        const result = parseRouteKey(`${method} /test`);
+        expect(result.method).toBe(method);
+      }
+    });
+
+    it("handles paths with namespace", () => {
+      const result = parseRouteKey("POST /api/v2/users");
+      expect(result).toEqual({
+        method: "POST",
+        path: "/api/v2/users",
+        pattern: expect.any(RegExp),
+        params: [],
+      });
+    });
+
+    it("creates correct regex pattern for simple path", () => {
+      const result = parseRouteKey("GET /users");
+      expect("/users").toMatch(result.pattern);
+      expect("/users/123").not.toMatch(result.pattern);
+    });
+
+    it("creates correct regex pattern with parameters", () => {
+      const result = parseRouteKey("GET /users/:id");
+      expect("/users/123").toMatch(result.pattern);
+      expect("/users/abc-def").toMatch(result.pattern);
+      expect("/users").not.toMatch(result.pattern);
+      expect("/users/").not.toMatch(result.pattern);
+      expect("/users/123/posts").not.toMatch(result.pattern);
+    });
+  });
+
+  describe("invalid route keys", () => {
+    it("throws on missing method", () => {
+      expect(() => parseRouteKey("/users")).toThrow("Invalid route key format");
+    });
+
+    it("throws on missing path", () => {
+      expect(() => parseRouteKey("GET")).toThrow("Invalid route key format");
+    });
+
+    it("throws on invalid method", () => {
+      expect(() => parseRouteKey("INVALID /users")).toThrow(
+        "Invalid route key format",
+      );
+    });
+
+    it("throws on lowercase method", () => {
+      expect(() => parseRouteKey("get /users")).toThrow(
+        "Invalid route key format",
+      );
+    });
+
+    it("throws on missing space", () => {
+      expect(() => parseRouteKey("GET/users")).toThrow(
+        "Invalid route key format",
+      );
+    });
+
+    it("throws on empty string", () => {
+      expect(() => parseRouteKey("")).toThrow("Invalid route key format");
+    });
+  });
+
+  describe("parameter extraction", () => {
+    it("extracts matched parameters", () => {
+      const route = parseRouteKey("GET /users/:userId/posts/:postId");
+      const match = "/users/123/posts/456".match(route.pattern);
+
+      expect(match).toBeTruthy();
+      expect(match?.[1]).toBe("123");
+      expect(match?.[2]).toBe("456");
+    });
+
+    it("handles special characters in parameters", () => {
+      const route = parseRouteKey("GET /files/:filename");
+      const match = "/files/report-2023.pdf".match(route.pattern);
+
+      expect(match).toBeTruthy();
+      expect(match?.[1]).toBe("report-2023.pdf");
+    });
+  });
+});

package/src/parser.ts

@@ -0,0 +1,61 @@
+import { RouteParseError } from "./errors";
+import type { HttpMethod } from "./types";
+
+export interface ParsedRoute {
+  method: HttpMethod;
+  path: string;
+  pattern: RegExp;
+  params: string[];
+}
+
+/**
+ * Parse 'METHOD /path' route key format
+ *
+ * Design note: We validate the format strictly to catch typos early.
+ * The 'METHOD /path' format was chosen for its readability and
+ * similarity to API documentation formats.
+ *
+ * @example
+ * parseRouteKey('GET /users/:id')
+ * // => { method: 'GET', path: '/users/:id', pattern: /^\/users\/([^/]+)$/, params: ['id'] }
+ */
+export function parseRouteKey(routeKey: string): ParsedRoute {
+  const match = routeKey.match(
+    /^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS) (.+)$/,
+  );
+
+  if (!match) {
+    throw new RouteParseError(
+      routeKey,
+      'Expected format: "METHOD /path" (e.g., "GET /users")',
+    );
+  }
+
+  const [, method, path] = match;
+
+  // Extract parameter names
+  const params: string[] = [];
+  const paramPattern = /:([^/]+)/g;
+  let paramMatch: RegExpExecArray | null;
+
+  paramMatch = paramPattern.exec(path);
+  while (paramMatch !== null) {
+    params.push(paramMatch[1]);
+    paramMatch = paramPattern.exec(path);
+  }
+
+  // Build regex pattern for matching
+  // Replace :param with capture groups
+  const regexPath = path
+    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&") // Escape special regex chars except :
+    .replace(/:([^/]+)/g, "([^/]+)"); // Replace :param with capture group
+
+  const pattern = new RegExp(`^${regexPath}$`);
+
+  return {
+    method: method as HttpMethod,
+    path,
+    pattern,
+    params,
+  };
+}