@schmock/core 1.0.3 → 1.1.0

package/src/builder.ts

@@ -5,19 +5,10 @@ import {
   SchmockError,
 } from "./errors.js";
 import { parseRouteKey } from "./parser.js";
-import type {
-  Generator,
-  GeneratorFunction,
-  GlobalConfig,
-  HttpMethod,
-  Plugin,
-  PluginContext,
-  RequestContext,
-  RequestOptions,
-  Response,
-  RouteConfig,
-  RouteKey,
-} from "./types.js";
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Unknown error";
+}
 
 /**
  * Debug logger that respects debug mode configuration
@@ -25,7 +16,7 @@ import type {
 class DebugLogger {
   constructor(private enabled = false) {}
 
-  log(category: string, message: string, data?: any) {
+  log(category: string, message: string, data?: unknown) {
     if (!this.enabled) return;
 
     const timestamp = new Date().toISOString();
@@ -55,10 +46,29 @@ class DebugLogger {
 interface CompiledCallableRoute {
   pattern: RegExp;
   params: string[];
-  method: HttpMethod;
+  method: Schmock.HttpMethod;
   path: string;
-  generator: Generator;
-  config: RouteConfig;
+  generator: Schmock.Generator;
+  config: Schmock.RouteConfig;
+}
+
+function isGeneratorFunction(
+  gen: Schmock.Generator,
+): gen is Schmock.GeneratorFunction {
+  return typeof gen === "function";
+}
+
+function isResponseObject(value: unknown): value is {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+} {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "status" in value &&
+    "body" in value
+  );
 }
 
 /**
@@ -68,10 +78,12 @@ interface CompiledCallableRoute {
  */
 export class CallableMockInstance {
   private routes: CompiledCallableRoute[] = [];
-  private plugins: Plugin[] = [];
+  private staticRoutes = new Map<string, CompiledCallableRoute>();
+  private plugins: Schmock.Plugin[] = [];
   private logger: DebugLogger;
+  private requestHistory: Schmock.RequestRecord[] = [];
 
-  constructor(private globalConfig: GlobalConfig = {}) {
+  constructor(private globalConfig: Schmock.GlobalConfig = {}) {
     this.logger = new DebugLogger(globalConfig.debug || false);
     if (globalConfig.debug) {
       this.logger.log("config", "Debug mode enabled");
@@ -85,9 +97,9 @@ export class CallableMockInstance {
 
   // Method for defining routes (called when instance is invoked)
   defineRoute(
-    route: RouteKey,
-    generator: Generator,
-    config: RouteConfig,
+    route: Schmock.RouteKey,
+    generator: Schmock.Generator,
+    config: Schmock.RouteConfig,
   ): this {
     // Auto-detect contentType if not provided
     if (!config.contentType) {
@@ -128,6 +140,17 @@ export class CallableMockInstance {
     // Parse the route key to create pattern and extract parameters
     const parsed = parseRouteKey(route);
 
+    // Check for duplicate routes
+    const existing = this.routes.find(
+      (r) => r.method === parsed.method && r.path === parsed.path,
+    );
+    if (existing) {
+      this.logger.log(
+        "warning",
+        `Duplicate route: ${route} — first registration wins`,
+      );
+    }
+
     // Compile the route
     const compiledRoute: CompiledCallableRoute = {
       pattern: parsed.pattern,
@@ -139,6 +162,20 @@ export class CallableMockInstance {
     };
 
     this.routes.push(compiledRoute);
+
+    // Store static routes (no params) in Map for O(1) lookup
+    // Only store the first registration — "first registration wins" semantics
+    if (parsed.params.length === 0) {
+      const normalizedPath =
+        parsed.path.endsWith("/") && parsed.path !== "/"
+          ? parsed.path.slice(0, -1)
+          : parsed.path;
+      const key = `${parsed.method} ${normalizedPath}`;
+      if (!this.staticRoutes.has(key)) {
+        this.staticRoutes.set(key, compiledRoute);
+      }
+    }
+
     this.logger.log("route", `Route defined: ${route}`, {
       contentType: config.contentType,
       generatorType: typeof generator,
@@ -148,7 +185,7 @@ export class CallableMockInstance {
     return this;
   }
 
-  pipe(plugin: Plugin): this {
+  pipe(plugin: Schmock.Plugin): this {
     this.plugins.push(plugin);
     this.logger.log(
       "plugin",
@@ -163,12 +200,83 @@ export class CallableMockInstance {
     return this;
   }
 
+  // ===== Request Spy / History API =====
+
+  history(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord[] {
+    if (method && path) {
+      return this.requestHistory.filter(
+        (r) => r.method === method && r.path === path,
+      );
+    }
+    return [...this.requestHistory];
+  }
+
+  called(method?: Schmock.HttpMethod, path?: string): boolean {
+    if (method && path) {
+      return this.requestHistory.some(
+        (r) => r.method === method && r.path === path,
+      );
+    }
+    return this.requestHistory.length > 0;
+  }
+
+  callCount(method?: Schmock.HttpMethod, path?: string): number {
+    if (method && path) {
+      return this.requestHistory.filter(
+        (r) => r.method === method && r.path === path,
+      ).length;
+    }
+    return this.requestHistory.length;
+  }
+
+  lastRequest(
+    method?: Schmock.HttpMethod,
+    path?: string,
+  ): Schmock.RequestRecord | undefined {
+    if (method && path) {
+      const filtered = this.requestHistory.filter(
+        (r) => r.method === method && r.path === path,
+      );
+      return filtered[filtered.length - 1];
+    }
+    return this.requestHistory[this.requestHistory.length - 1];
+  }
+
+  // ===== Reset / Lifecycle =====
+
+  reset(): void {
+    this.routes = [];
+    this.staticRoutes.clear();
+    this.plugins = [];
+    this.requestHistory = [];
+    if (this.globalConfig.state) {
+      for (const key of Object.keys(this.globalConfig.state)) {
+        delete this.globalConfig.state[key];
+      }
+    }
+    this.logger.log("lifecycle", "Mock fully reset");
+  }
+
+  resetHistory(): void {
+    this.requestHistory = [];
+    this.logger.log("lifecycle", "Request history cleared");
+  }
+
+  resetState(): void {
+    if (this.globalConfig.state) {
+      for (const key of Object.keys(this.globalConfig.state)) {
+        delete this.globalConfig.state[key];
+      }
+    }
+    this.logger.log("lifecycle", "State cleared");
+  }
+
   async handle(
-    method: HttpMethod,
+    method: Schmock.HttpMethod,
     path: string,
-    options?: RequestOptions,
-  ): Promise<Response> {
-    const requestId = Math.random().toString(36).substring(7);
+    options?: Schmock.RequestOptions,
+  ): Promise<Schmock.Response> {
+    const requestId = crypto.randomUUID();
     this.logger.log("request", `[${requestId}] ${method} ${path}`, {
       headers: options?.headers,
       query: options?.query,
@@ -179,46 +287,40 @@ export class CallableMockInstance {
     try {
       // Apply namespace if configured
       let requestPath = path;
-      if (this.globalConfig.namespace) {
-        // Normalize namespace to handle edge cases
-        const namespace = this.globalConfig.namespace;
-        if (namespace === "/") {
-          // Root namespace means no transformation needed
-          requestPath = path;
-        } else {
-          // Handle namespace without leading slash by normalizing both namespace and path
-          const normalizedNamespace = namespace.startsWith("/")
-            ? namespace
-            : `/${namespace}`;
-          const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-
-          // Remove trailing slash from namespace unless it's root
-          const finalNamespace =
-            normalizedNamespace.endsWith("/") && normalizedNamespace !== "/"
-              ? normalizedNamespace.slice(0, -1)
-              : normalizedNamespace;
-
-          if (!normalizedPath.startsWith(finalNamespace)) {
-            this.logger.log(
-              "route",
-              `[${requestId}] Path doesn't match namespace ${namespace}`,
-            );
-            const error = new RouteNotFoundError(method, path);
-            const response = {
-              status: 404,
-              body: { error: error.message, code: error.code },
-              headers: {},
-            };
-            this.logger.timeEnd(`request-${requestId}`);
-            return response;
-          }
+      if (this.globalConfig.namespace && this.globalConfig.namespace !== "/") {
+        const namespace = this.globalConfig.namespace.startsWith("/")
+          ? this.globalConfig.namespace
+          : `/${this.globalConfig.namespace}`;
+
+        const pathToCheck = path.startsWith("/") ? path : `/${path}`;
+
+        // Check if path starts with namespace
+        // handle both "/api/users" (starts with /api) and "/api" (exact match)
+        // but NOT "/apiv2" (prefix match but wrong segment)
+        const isMatch =
+          pathToCheck === namespace ||
+          pathToCheck.startsWith(
+            namespace.endsWith("/") ? namespace : `${namespace}/`,
+          );
 
-          // Remove namespace prefix, ensuring we always start with /
-          requestPath = normalizedPath.substring(finalNamespace.length);
-          if (!requestPath.startsWith("/")) {
-            requestPath = `/${requestPath}`;
-          }
+        if (!isMatch) {
+          this.logger.log(
+            "route",
+            `[${requestId}] Path doesn't match namespace ${namespace}`,
+          );
+          const error = new RouteNotFoundError(method, path);
+          const response = {
+            status: 404,
+            body: { error: error.message, code: error.code },
+            headers: {},
+          };
+          this.logger.timeEnd(`request-${requestId}`);
+          return response;
         }
+
+        // Remove namespace prefix, ensuring we always start with /
+        const stripped = pathToCheck.slice(namespace.length);
+        requestPath = stripped.startsWith("/") ? stripped : `/${stripped}`;
       }
 
       // Find matching route
@@ -248,7 +350,7 @@ export class CallableMockInstance {
       const params = this.extractParams(matchedRoute, requestPath);
 
       // Generate initial response from route handler
-      const context: RequestContext = {
+      const context: Schmock.RequestContext = {
         method,
         path: requestPath,
         params,
@@ -258,15 +360,15 @@ export class CallableMockInstance {
         state: this.globalConfig.state || {},
       };
 
-      let result: any;
-      if (typeof matchedRoute.generator === "function") {
-        result = await (matchedRoute.generator as GeneratorFunction)(context);
+      let result: unknown;
+      if (isGeneratorFunction(matchedRoute.generator)) {
+        result = await matchedRoute.generator(context);
       } else {
         result = matchedRoute.generator;
       }
 
       // Build plugin context
-      let pluginContext: PluginContext = {
+      let pluginContext: Schmock.PluginContext = {
         path: requestPath,
         route: matchedRoute.config,
         method,
@@ -291,7 +393,7 @@ export class CallableMockInstance {
       } catch (error) {
         this.logger.log(
           "error",
-          `[${requestId}] Plugin pipeline error: ${(error as Error).message}`,
+          `[${requestId}] Plugin pipeline error: ${errorMessage(error)}`,
         );
         throw error;
       }
@@ -302,6 +404,18 @@ export class CallableMockInstance {
       // Apply global delay if configured
       await this.applyDelay();
 
+      // Record request in history
+      this.requestHistory.push({
+        method,
+        path: requestPath,
+        params,
+        query: options?.query || {},
+        headers: options?.headers || {},
+        body: options?.body,
+        timestamp: Date.now(),
+        response: { status: response.status, body: response.body },
+      });
+
       // Log successful response
       this.logger.log(
         "response",
@@ -318,7 +432,7 @@ export class CallableMockInstance {
     } catch (error) {
       this.logger.log(
         "error",
-        `[${requestId}] Error processing request: ${(error as Error).message}`,
+        `[${requestId}] Error processing request: ${errorMessage(error)}`,
         error,
       );
 
@@ -326,11 +440,8 @@ export class CallableMockInstance {
       const errorResponse = {
         status: 500,
         body: {
-          error: (error as Error).message,
-          code:
-            error instanceof SchmockError
-              ? (error as SchmockError).code
-              : "INTERNAL_ERROR",
+          error: errorMessage(error),
+          code: error instanceof SchmockError ? error.code : "INTERNAL_ERROR",
         },
         headers: {},
       };
@@ -371,20 +482,18 @@ export class CallableMockInstance {
    * @returns Normalized Response object with status, body, and headers
    * @private
    */
-  private parseResponse(result: any, routeConfig: RouteConfig): Response {
+  private parseResponse(
+    result: unknown,
+    routeConfig: Schmock.RouteConfig,
+  ): Schmock.Response {
     let status = 200;
-    let body = result;
+    let body: unknown = result;
     let headers: Record<string, string> = {};
 
     let tupleFormat = false;
 
     // Handle already-formed response objects (from plugin error recovery)
-    if (
-      result &&
-      typeof result === "object" &&
-      "status" in result &&
-      "body" in result
-    ) {
+    if (isResponseObject(result)) {
       return {
         status: result.status,
         body: result.body,
@@ -441,13 +550,13 @@ export class CallableMockInstance {
    * @private
    */
   private async runPluginPipeline(
-    context: PluginContext,
-    initialResponse?: any,
-    _routeConfig?: RouteConfig,
+    context: Schmock.PluginContext,
+    initialResponse?: unknown,
+    _routeConfig?: Schmock.RouteConfig,
     _requestId?: string,
-  ): Promise<{ context: PluginContext; response?: any }> {
+  ): Promise<{ context: Schmock.PluginContext; response?: unknown }> {
     let currentContext = context;
-    let response: any = initialResponse;
+    let response: unknown = initialResponse;
 
     this.logger.log(
       "pipeline",
@@ -486,14 +595,16 @@ export class CallableMockInstance {
       } catch (error) {
         this.logger.log(
           "pipeline",
-          `Plugin ${plugin.name} failed: ${(error as Error).message}`,
+          `Plugin ${plugin.name} failed: ${errorMessage(error)}`,
         );
 
         // Try error handling if plugin has onError hook
         if (plugin.onError) {
           try {
+            const pluginError =
+              error instanceof Error ? error : new Error(errorMessage(error));
             const errorResult = await plugin.onError(
-              error as Error,
+              pluginError,
               currentContext,
             );
             if (errorResult) {
@@ -501,22 +612,38 @@ export class CallableMockInstance {
                 "pipeline",
                 `Plugin ${plugin.name} handled error`,
               );
-              // If error handler returns response, use it and stop pipeline
-              if (typeof errorResult === "object" && errorResult.status) {
-                // Return the error response as the current response, stop pipeline
+
+              // Error return → transform the thrown error
+              if (errorResult instanceof Error) {
+                throw new PluginError(plugin.name, errorResult);
+              }
+
+              // ResponseResult return → recover, stop pipeline
+              if (
+                typeof errorResult === "object" &&
+                errorResult !== null &&
+                "status" in errorResult
+              ) {
                 response = errorResult;
                 break;
               }
             }
+            // void/falsy return → propagate original error below
           } catch (hookError) {
+            // If the hook itself threw (including our PluginError above), re-throw it
+            if (hookError instanceof PluginError) {
+              throw hookError;
+            }
             this.logger.log(
               "pipeline",
-              `Plugin ${plugin.name} error handler failed: ${(hookError as Error).message}`,
+              `Plugin ${plugin.name} error handler failed: ${errorMessage(hookError)}`,
             );
           }
         }
 
-        throw new PluginError(plugin.name, error as Error);
+        const cause =
+          error instanceof Error ? error : new Error(errorMessage(error));
+        throw new PluginError(plugin.name, cause);
       }
     }
 
@@ -533,21 +660,18 @@ export class CallableMockInstance {
    * @private
    */
   private findRoute(
-    method: HttpMethod,
+    method: Schmock.HttpMethod,
     path: string,
   ): CompiledCallableRoute | undefined {
-    // First pass: Look for static routes (routes without parameters)
-    for (const route of this.routes) {
-      if (
-        route.method === method &&
-        route.params.length === 0 &&
-        route.pattern.test(path)
-      ) {
-        return route;
-      }
+    // O(1) lookup for static routes
+    const normalizedPath =
+      path.endsWith("/") && path !== "/" ? path.slice(0, -1) : path;
+    const staticMatch = this.staticRoutes.get(`${method} ${normalizedPath}`);
+    if (staticMatch) {
+      return staticMatch;
     }
 
-    // Second pass: Look for parameterized routes
+    // Fall through to parameterized route scan
     for (const route of this.routes) {
       if (
         route.method === method &&

package/src/constants.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import {
+  HTTP_METHODS,
+  isHttpMethod,
+  ROUTE_NOT_FOUND_CODE,
+  toHttpMethod,
+} from "./constants";
+
+describe("constants", () => {
+  it("exports ROUTE_NOT_FOUND_CODE", () => {
+    expect(ROUTE_NOT_FOUND_CODE).toBe("ROUTE_NOT_FOUND");
+  });
+
+  it("exports all HTTP methods", () => {
+    expect(HTTP_METHODS).toEqual([
+      "GET",
+      "POST",
+      "PUT",
+      "DELETE",
+      "PATCH",
+      "HEAD",
+      "OPTIONS",
+    ]);
+  });
+});
+
+describe("isHttpMethod", () => {
+  it("returns true for valid HTTP methods", () => {
+    for (const method of HTTP_METHODS) {
+      expect(isHttpMethod(method)).toBe(true);
+    }
+  });
+
+  it("returns false for invalid methods", () => {
+    expect(isHttpMethod("INVALID")).toBe(false);
+    expect(isHttpMethod("")).toBe(false);
+    expect(isHttpMethod("get")).toBe(false);
+  });
+});
+
+describe("toHttpMethod", () => {
+  it("converts lowercase to uppercase", () => {
+    expect(toHttpMethod("get")).toBe("GET");
+    expect(toHttpMethod("post")).toBe("POST");
+    expect(toHttpMethod("delete")).toBe("DELETE");
+  });
+
+  it("returns already uppercase methods", () => {
+    expect(toHttpMethod("GET")).toBe("GET");
+    expect(toHttpMethod("PATCH")).toBe("PATCH");
+  });
+
+  it("throws for invalid methods", () => {
+    expect(() => toHttpMethod("INVALID")).toThrow(
+      'Invalid HTTP method: "INVALID"',
+    );
+    expect(() => toHttpMethod("")).toThrow('Invalid HTTP method: ""');
+  });
+});

package/src/constants.ts

@@ -0,0 +1,25 @@
+import type { HttpMethod } from "./types.js";
+
+export const ROUTE_NOT_FOUND_CODE = "ROUTE_NOT_FOUND" as const;
+
+export const HTTP_METHODS: readonly HttpMethod[] = [
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+] as const;
+
+export function isHttpMethod(method: string): method is HttpMethod {
+  return (HTTP_METHODS as readonly string[]).includes(method);
+}
+
+export function toHttpMethod(method: string): HttpMethod {
+  const upper = method.toUpperCase();
+  if (!isHttpMethod(upper)) {
+    throw new Error(`Invalid HTTP method: "${method}"`);
+  }
+  return upper;
+}

package/src/errors.ts

@@ -9,7 +9,9 @@ export class SchmockError extends Error {
   ) {
     super(message);
     this.name = "SchmockError";
-    Error.captureStackTrace(this, this.constructor);
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, this.constructor);
+    }
   }
 }