feat: Pass more detail to response creator functions (#67)

Author: nzakas

docs/src/content/docs/mock-servers/extended-response-patterns.mdx

@@ -161,3 +161,43 @@ server.get("/users/123", async request => {
 ```
 
 This route will respond to any GET request to `/users/123` with a status code of 200 and a JSON response body containing an `id` and `name` property, but it will wait for 1 second before returning the response. You can use this to simulate network latency or other asynchronous behavior when the `delay` key is not sufficient.
+
+### Access request context in response creators
+
+Response creator functions receive a second argument that provides access to additional request context information. This object contains:
+
+- `cookies` - A `Map` containing any cookies sent with the request
+- `params` - An object containing any URL parameters matched in the route pattern
+- `query` - A `URLSearchParams` object containing any query string parameters
+
+Here's an example showing how to use this context:
+
+```js
+import { MockServer } from "mentoss";
+
+const server = new MockServer("https://api.example.com");
+
+// Match URLs like /users/123
+server.get("/users/:id", (request, { cookies, params, query }) => {
+    
+    // Access cookies
+    const sessionId = cookies.get("sessionId");
+    
+    // Access URL parameters
+    const userId = params.id;
+    
+    // Access query string parameters
+	const format = query.get("format") ?? "json";
+    
+    return {
+        status: 200,
+        body: {
+            userId,
+            sessionId,
+            format
+        }
+    };
+});
+```
+
+The context argument makes it easy to implement realistic API behaviors that depend on these request details.

src/mock-server.js

@@ -132,6 +132,26 @@ function assertValidResponsePattern(responsePattern) {
 	}
 }
 
+/**
+ * Parses cookies from a Cookie header value
+ * @param {string|null} cookieHeader The Cookie header value
+ * @returns {Map<string,string>} A map of cookie names to values
+ */
+function parseCookies(cookieHeader) {
+    const cookies = new Map();
+    
+    if (!cookieHeader) {
+        return cookies;
+    }
+
+	cookieHeader.split(";").forEach(cookie => {
+		const [name, value] = cookie.trim().split("=");
+		cookies.set(decodeURIComponent(name), decodeURIComponent(value));
+	});
+
+    return cookies;
+}
+
 /**
  * Represents a route that the server can respond to.
  */
@@ -209,8 +229,19 @@ export class Route {
 	 * @returns {Promise<Response>} The response to return.
 	 */
 	async createResponse(request, PreferredResponse) {
+		const requestMatch = this.#matcher.traceMatches({
+            method: request.method,
+            url: request.url,
+            headers: Object.fromEntries([...request.headers.entries()]),
+        });
+        
+        const cookies = parseCookies(request.headers.get('cookie'));
+        const response = await this.#createResponse(request, {
+			cookies,
+			params: requestMatch.params,
+			query: requestMatch.query,
+		});
 
-		const response = await this.#createResponse(request);
 		const { body, delay, ...init } = typeof response === "number" ? { status: response } : response;
 
 		if (!init.status) {

src/request-matcher.js

@@ -3,7 +3,7 @@
  * @author Nicholas C. Zakas
  */
 
-/* globals FormData, URLPattern */
+/* globals FormData, URLPattern, URLSearchParams */
 
 //-----------------------------------------------------------------------------
 // Imports
@@ -117,32 +117,38 @@ export class RequestMatcher {
 	 * Checks if the request matches the matcher. Traces all of the details to help
 	 * with debugging.
 	 * @param {RequestPattern} request The request to check.
-	 * @returns {{matches:boolean, messages:string[]}} True if the request matches, false if not.
+	 * @returns {{matches:boolean, messages:string[], params:Record<string, string|undefined>, query:URLSearchParams}} True if the request matches, false if not.
 	 */
 	traceMatches(request) {
+		
 		/*
 		 * Check the URL first. This is helpful for tracing when requests don't match
 		 * because people more typically get the method wrong rather than the URL.
 		 */
-		// then check the URL
 		const urlMatch = this.#pattern.exec(request.url);
 		if (!urlMatch) {
 			return {
 				matches: false,
 				messages: ["❌ URL does not match."],
+				params: {},
+				query: new URLSearchParams(),
 			};
 		}
 
 		const messages = ["✅ URL matches."];
+		const params = urlMatch.pathname.groups;
+		const query = new URL(request.url).searchParams;
 
-		// first check the method
+		// Method check
 		if (request.method.toLowerCase() !== this.#method.toLowerCase()) {
 			return {
 				matches: false,
 				messages: [
 					...messages,
 					`❌ Method does not match. Expected ${this.#method.toUpperCase()} but received ${request.method.toUpperCase()}.`,
-				],
+					],
+				params,
+				query,
 			};
 		}
 
@@ -161,6 +167,8 @@ export class RequestMatcher {
 						...messages,
 						"❌ Query string does not match. Expected query string but received none.",
 					],
+					params,
+					query,
 				};
 			}
 
@@ -172,6 +180,8 @@ export class RequestMatcher {
 							...messages,
 							`❌ Query string does not match. Expected ${key}=${value} but received ${key}=${actualQuery[key]}.`,
 						],
+						params,
+						query,
 					};
 				}
 			}
@@ -190,6 +200,8 @@ export class RequestMatcher {
 						...messages,
 						"❌ URL parameters do not match. Expected parameters but received none.",
 					],
+					params,
+					query,
 				};
 			}
 
@@ -201,6 +213,8 @@ export class RequestMatcher {
 							...messages,
 							`❌ URL parameters do not match. Expected ${key}=${value} but received ${key}=${actualParams[key]}.`,
 						],
+						params,
+						query,
 					};
 				}
 			}
@@ -228,6 +242,8 @@ export class RequestMatcher {
 							...messages,
 							`❌ Headers do not match. Expected ${key}=${value} but received ${key}=${actualValue ? actualValue[1] : "none"}.`,
 						],
+						params,
+						query,
 					};
 				}
 			}
@@ -245,6 +261,8 @@ export class RequestMatcher {
 						...messages,
 						"❌ Body does not match. Expected body but received none.",
 					],
+					params,
+					query,
 				};
 			}
 
@@ -256,6 +274,8 @@ export class RequestMatcher {
 							...messages,
 							`❌ Body does not match. Expected ${this.#body} but received ${request.body}`,
 						],
+						params,
+						query,
 					};
 				}
 
@@ -268,6 +288,8 @@ export class RequestMatcher {
 							...messages,
 							"❌ Body does not match. Expected FormData but received none.",
 						],
+						params,
+						query,
 					};
 				}
 
@@ -279,6 +301,8 @@ export class RequestMatcher {
 								...messages,
 								`❌ Body does not match. Expected ${key}=${value} but received ${key}=${request.body.get(key)}.`,
 							],
+							params,
+							query,
 						};
 					}
 				}
@@ -292,6 +316,8 @@ export class RequestMatcher {
 							...messages,
 							`❌ Body does not match. Expected ArrayBuffer but received ${request.body.constructor.name}.`,
 						],
+						params,
+						query,
 					};
 				}
 
@@ -303,6 +329,8 @@ export class RequestMatcher {
 							...messages,
 							`❌ Body does not match. Expected array buffer byte length ${this.#body.byteLength} but received ${request.body.byteLength}`,
 						],
+						params,
+						query,
 					};
 				}
 
@@ -318,6 +346,8 @@ export class RequestMatcher {
 								...messages,
 								`❌ Body does not match. Expected byte ${i} to be ${expectedBody[i]} but received ${actualBody[i]}.`,
 							],
+							params,
+							query,
 						};
 					}
 				}
@@ -332,6 +362,8 @@ export class RequestMatcher {
 							...messages,
 							"❌ Body does not match. Expected object but received none.",
 						],
+						params,
+						query,
 					};
 				}
 
@@ -343,6 +375,8 @@ export class RequestMatcher {
 							...messages,
 							`❌ Body does not match. Expected ${JSON.stringify(this.#body)} but received ${JSON.stringify(request.body)}.`,
 						],
+						params,
+						query,
 					};
 				}
 
@@ -353,6 +387,8 @@ export class RequestMatcher {
 		return {
 			matches: true,
 			messages,
+			params,
+			query,
 		};
 	}
 

src/types.ts

@@ -38,12 +38,33 @@ export interface ResponsePattern {
 	delay?: number;
 }
 
+/**
+ * Additional information that's helpful for evaluating a request.
+ */
+export interface RequestInfo {
+	
+	/**
+	 * The cookies sent with the request.
+	 */
+	cookies: Map<string, string>;
+	
+	/**
+	 * The URL parameters found in the request.
+	 */
+	params: Record<string, string|undefined>;
+	
+	/**
+	 * The query parameters found in the request.
+	 */
+	query: URLSearchParams;
+}
+
 /**
  * Create a response based on the request.
  * @param request The request to create a response for.
  * @returns The response to send back.
  */
-export type ResponseCreator = (request: Request) => ResponsePattern | number | Promise<ResponsePattern> | Promise<number>;
+export type ResponseCreator = (request: Request, requestInfo: RequestInfo) => ResponsePattern | number | Promise<ResponsePattern> | Promise<number>;
 
 export interface Credentials {
 	/**

tests/mock-server.test.js

@@ -3,7 +3,7 @@
  * @author Nicholas C. Zakas
  */
 
-/* globals FormData, Request, TextEncoder */
+/* globals FormData, Request, TextEncoder, URLSearchParams */
 
 //-----------------------------------------------------------------------------
 // Imports
@@ -330,6 +330,62 @@ describe("MockServer", () => {
 				await server.receive(request);
 			});
 
+			it("should pass request info object as second parameter to response creator", async () => {
+				server.get("/users/:id", (request, info) => {
+					assert.ok(info.cookies instanceof Map);
+					assert.ok(info.query instanceof URLSearchParams);
+					assert.strictEqual(typeof info.params, "object");
+					
+					assert.strictEqual(info.cookies.get("session"), "abc123");
+					assert.strictEqual(info.params.id, "123");
+					assert.strictEqual(info.query.get("sort"), "asc");
+					
+					return { status: 200, body: "OK" };
+				});
+		
+				const request = createRequest({
+					method: "GET",
+					url: `${BASE_URL}/users/123?sort=asc`,
+					headers: {
+						Cookie: "session=abc123"
+					}
+				});
+		
+				const response = await server.receive(request);
+				assert.strictEqual(response.status, 200);
+			});
+			
+			it("should provide empty cookies map when no cookies present", async () => {
+				server.get("/test", (request, info) => {
+					assert.strictEqual(info.cookies.size, 0);
+					return { status: 200 };
+				});
+		
+				const request = createRequest({
+					method: "GET",
+					url: `${BASE_URL}/test`
+				});
+		
+				await server.receive(request);
+			});
+		
+			it("should parse multiple cookies correctly", async () => {
+				server.get("/test", (request, info) => {
+					assert.strictEqual(info.cookies.get("session"), "abc123");
+					assert.strictEqual(info.cookies.get("user"), "john");
+					return { status: 200 };
+				});
+		
+				const request = createRequest({
+					method: "GET",
+					url: `${BASE_URL}/test`,
+					headers: {
+						Cookie: "session=abc123; user=john"
+					}
+				});
+		
+				await server.receive(request);
+			});
 		});
 	});