@schmock/core 1.0.4 → 1.2.1

package/src/builder.ts

@@ -1,3 +1,4 @@
+import { isStatusTuple } from "./constants.js";
 import {
   PluginError,
   RouteDefinitionError,
@@ -5,19 +6,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 +17,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 +47,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 +79,13 @@ 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[] = [];
+  private callableRef: Schmock.CallableMockInstance | undefined;
 
-  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 +99,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) {
@@ -150,6 +164,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,
@@ -159,7 +187,11 @@ export class CallableMockInstance {
     return this;
   }
 
-  pipe(plugin: Plugin): this {
+  setCallableRef(ref: Schmock.CallableMockInstance): void {
+    this.callableRef = ref;
+  }
+
+  pipe(plugin: Schmock.Plugin): this {
     this.plugins.push(plugin);
     this.logger.log(
       "plugin",
@@ -171,15 +203,89 @@ export class CallableMockInstance {
         hasOnError: typeof plugin.onError === "function",
       },
     );
+    if (plugin.install && this.callableRef) {
+      plugin.install(this.callableRef);
+    }
     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(2, 10) || "00000000";
+    options?: Schmock.RequestOptions,
+  ): Promise<Schmock.Response> {
+    const requestId = crypto.randomUUID();
     this.logger.log("request", `[${requestId}] ${method} ${path}`, {
       headers: options?.headers,
       query: options?.query,
@@ -190,46 +296,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
@@ -259,7 +359,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,
@@ -269,15 +369,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,
@@ -302,7 +402,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;
       }
@@ -313,6 +413,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",
@@ -329,7 +441,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,
       );
 
@@ -337,11 +449,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: {},
       };
@@ -382,20 +491,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,
@@ -404,7 +511,7 @@ export class CallableMockInstance {
     }
 
     // Handle tuple response format [status, body, headers?]
-    if (Array.isArray(result) && typeof result[0] === "number") {
+    if (isStatusTuple(result)) {
       [status, body, headers = {}] = result;
       tupleFormat = true;
     }
@@ -452,13 +559,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",
@@ -497,14 +604,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) {
@@ -512,26 +621,38 @@ export class CallableMockInstance {
                 "pipeline",
                 `Plugin ${plugin.name} handled error`,
               );
-              // If error handler returns response, use it and 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
               ) {
-                // Return the error response as the current response, stop pipeline
                 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);
       }
     }
 
@@ -548,21 +669,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.ts

@@ -13,7 +13,7 @@ export const HTTP_METHODS: readonly HttpMethod[] = [
 ] as const;
 
 export function isHttpMethod(method: string): method is HttpMethod {
-  return HTTP_METHODS.includes(method as HttpMethod);
+  return (HTTP_METHODS as readonly string[]).includes(method);
 }
 
 export function toHttpMethod(method: string): HttpMethod {
@@ -23,3 +23,19 @@ export function toHttpMethod(method: string): HttpMethod {
   }
   return upper;
 }
+
+/**
+ * Check if a value is a status tuple: [status, body] or [status, body, headers]
+ * Guards against misinterpreting numeric arrays like [1, 2, 3] as tuples.
+ */
+export function isStatusTuple(
+  value: unknown,
+): value is [number, unknown] | [number, unknown, Record<string, string>] {
+  return (
+    Array.isArray(value) &&
+    (value.length === 2 || value.length === 3) &&
+    typeof value[0] === "number" &&
+    value[0] >= 100 &&
+    value[0] <= 599
+  );
+}

package/src/index.ts

@@ -1,12 +1,4 @@
-import { CallableMockInstance as CallableMockInstanceImpl } from "./builder.js";
-import type {
-  CallableMockInstance,
-  Generator,
-  GlobalConfig,
-  Plugin,
-  RouteConfig,
-  RouteKey,
-} from "./types.js";
+import { CallableMockInstance } from "./builder.js";
 
 /**
  * Create a new Schmock mock instance with callable API.
@@ -31,34 +23,48 @@ import type {
  * @param config Optional global configuration
  * @returns A callable mock instance
  */
-export function schmock(config?: GlobalConfig): CallableMockInstance {
+export function schmock(
+  config?: Schmock.GlobalConfig,
+): Schmock.CallableMockInstance {
   // Always use new callable API
-  const instance = new CallableMockInstanceImpl(config || {});
+  const instance = new CallableMockInstance(config || {});
 
-  // Create a callable function that wraps the instance
-  const callableInstance = ((
-    route: RouteKey,
-    generator: Generator,
-    routeConfig: RouteConfig = {},
-  ) => {
-    instance.defineRoute(route, generator, routeConfig);
-    return callableInstance; // Return the callable function for chaining
-  }) as any;
+  // Callable proxy: a function with attached methods
+  const callableInstance: Schmock.CallableMockInstance = Object.assign(
+    (
+      route: Schmock.RouteKey,
+      generator: Schmock.Generator,
+      routeConfig: Schmock.RouteConfig = {},
+    ) => {
+      instance.defineRoute(route, generator, routeConfig);
+      return callableInstance;
+    },
+    {
+      pipe: (plugin: Schmock.Plugin) => {
+        instance.pipe(plugin);
+        return callableInstance;
+      },
+      handle: instance.handle.bind(instance),
+      history: instance.history.bind(instance),
+      called: instance.called.bind(instance),
+      callCount: instance.callCount.bind(instance),
+      lastRequest: instance.lastRequest.bind(instance),
+      reset: instance.reset.bind(instance),
+      resetHistory: instance.resetHistory.bind(instance),
+      resetState: instance.resetState.bind(instance),
+    },
+  );
 
-  // Manually bind all instance methods to the callable function with proper return values
-  callableInstance.pipe = (plugin: Plugin) => {
-    instance.pipe(plugin);
-    return callableInstance; // Return callable function for chaining
-  };
-  callableInstance.handle = instance.handle.bind(instance);
+  instance.setCallableRef(callableInstance);
 
-  return callableInstance as CallableMockInstance;
+  return callableInstance;
 }
 
 // Re-export constants and utilities
 export {
   HTTP_METHODS,
   isHttpMethod,
+  isStatusTuple,
   ROUTE_NOT_FOUND_CODE,
   toHttpMethod,
 } from "./constants.js";
@@ -74,7 +80,6 @@ export {
   SchemaValidationError,
   SchmockError,
 } from "./errors.js";
-
 // Re-export types
 export type {
   CallableMockInstance,
@@ -87,6 +92,7 @@ export type {
   PluginResult,
   RequestContext,
   RequestOptions,
+  RequestRecord,
   Response,
   ResponseBody,
   ResponseResult,

package/src/namespace.test.ts

@@ -95,8 +95,9 @@ describe("namespace functionality", () => {
       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);
+      // New logic gracefully handles double slashes by stripping the full namespace
+      expect(response2.status).toBe(200);
+      expect(response2.body).toBe("users");
     });
 
     it("handles empty namespace", async () => {