@fragno-dev/core 0.1.1 → 0.1.3

package/src/api/fragment-instantiation.ts

@@ -18,6 +18,7 @@ import {
   type FragnoMiddlewareCallback,
 } from "./request-middleware";
 import type { FragmentDefinition } from "./fragment-builder";
+import { MutableRequestState } from "./mutable-request-state";
 
 export interface FragnoPublicConfig {
   mountRoute?: string;
@@ -267,14 +268,25 @@ export function createFragment<
 
       const outputContext = new RequestOutputContext(outputSchema);
 
+      // Create mutable request state that can be modified by middleware
+      // Clone the request to avoid consuming the body stream
+      const clonedReq = req.clone();
+      const requestBody =
+        clonedReq.body instanceof ReadableStream ? await clonedReq.json() : undefined;
+
+      const requestState = new MutableRequestState({
+        pathParams: route.params ?? {},
+        searchParams: url.searchParams,
+        body: requestBody,
+        headers: new Headers(req.headers),
+      });
+
       if (middlewareHandler) {
         const middlewareInputContext = new RequestMiddlewareInputContext(routes, {
           method: req.method as HTTPMethod,
           path,
-          pathParams: route.params,
-          searchParams: new URL(req.url).searchParams,
-          body: req.body,
           request: req,
+          state: requestState,
         });
 
         const middlewareOutputContext = new RequestMiddlewareOutputContext(dependencies, services);
@@ -310,6 +322,7 @@ export function createFragment<
         path,
         pathParams: (route.params ?? {}) as ExtractPathParams<typeof path>,
         inputSchema,
+        state: requestState,
       });
 
       try {

package/src/api/mutable-request-state.ts

@@ -0,0 +1,107 @@
+import type { RequestBodyType } from "./request-input-context";
+
+/**
+ * Holds mutable request state that can be modified by middleware and consumed by handlers.
+ *
+ * This class provides a structural way for middleware to modify request data:
+ * - Path parameters can be modified
+ * - Query/search parameters can be modified
+ * - Request body can be overridden
+ * - Request headers can be modified
+ *
+ * @example
+ * ```typescript
+ * // In middleware
+ * const state = new MutableRequestState({
+ *   pathParams: { id: "123" },
+ *   searchParams: new URLSearchParams("?role=user"),
+ *   body: { name: "John" },
+ *   headers: new Headers()
+ * });
+ *
+ * // Modify query parameters
+ * state.searchParams.set("role", "admin");
+ *
+ * // Override body
+ * state.setBody({ name: "Jane" });
+ *
+ * // Modify headers
+ * state.headers.set("X-Custom", "value");
+ * ```
+ */
+export class MutableRequestState {
+  readonly #pathParams: Record<string, string>;
+  readonly #searchParams: URLSearchParams;
+  readonly #headers: Headers;
+  // oxlint-disable-next-line no-unused-private-class-members False Positive?
+  readonly #initialBody: RequestBodyType;
+  #bodyOverride: RequestBodyType | undefined;
+
+  constructor(config: {
+    pathParams: Record<string, string>;
+    searchParams: URLSearchParams;
+    body: RequestBodyType;
+    headers: Headers;
+  }) {
+    this.#pathParams = config.pathParams;
+    this.#searchParams = config.searchParams;
+    this.#headers = config.headers;
+    this.#initialBody = config.body;
+    this.#bodyOverride = undefined;
+  }
+
+  /**
+   * Path parameters extracted from the route.
+   * Can be modified directly (e.g., `state.pathParams.id = "456"`).
+   */
+  get pathParams(): Record<string, string> {
+    return this.#pathParams;
+  }
+
+  /**
+   * URLSearchParams for query parameters.
+   * Can be modified using URLSearchParams API (e.g., `state.searchParams.set("key", "value")`).
+   */
+  get searchParams(): URLSearchParams {
+    return this.#searchParams;
+  }
+
+  /**
+   * Request headers.
+   * Can be modified using Headers API (e.g., `state.headers.set("X-Custom", "value")`).
+   */
+  get headers(): Headers {
+    return this.#headers;
+  }
+
+  /**
+   * Get the current body value.
+   * Returns the override if set, otherwise the initial body.
+   */
+  get body(): RequestBodyType {
+    return this.#bodyOverride !== undefined ? this.#bodyOverride : this.#initialBody;
+  }
+
+  /**
+   * Override the request body.
+   * This allows middleware to replace the body that will be seen by the handler.
+   *
+   * @param body - The new body value
+   *
+   * @example
+   * ```typescript
+   * // In middleware
+   * state.setBody({ modifiedField: "new value" });
+   * ```
+   */
+  setBody(body: RequestBodyType): void {
+    this.#bodyOverride = body;
+  }
+
+  /**
+   * Check if the body has been overridden by middleware.
+   */
+  get hasBodyOverride(): boolean {
+    return this.#bodyOverride !== undefined;
+  }
+}

package/src/api/request-input-context.test.ts

@@ -2,6 +2,7 @@ import { test, expect, describe } from "vitest";
 import { RequestInputContext } from "./request-input-context";
 import { FragnoApiValidationError } from "./api";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { MutableRequestState } from "./mutable-request-state";
 
 // Mock schema implementations for testing
 const createMockSchema = (shouldPass: boolean, returnValue?: unknown): StandardSchemaV1 => ({
@@ -40,6 +41,7 @@ describe("RequestContext", () => {
       path: "/",
       pathParams: {},
       searchParams: new URLSearchParams(),
+      headers: new Headers(),
       body: undefined,
     });
 
@@ -59,6 +61,7 @@ describe("RequestContext", () => {
       path: "/api/test",
       pathParams: {},
       searchParams: new URLSearchParams(),
+      headers: new Headers(),
       body: jsonBody,
     });
 
@@ -73,6 +76,7 @@ describe("RequestContext", () => {
       path: "/api/form",
       pathParams: {},
       searchParams: new URLSearchParams(),
+      headers: new Headers(),
       body: formData,
       method: "POST",
     });
@@ -87,6 +91,7 @@ describe("RequestContext", () => {
       path: "/api/upload",
       pathParams: {},
       searchParams: new URLSearchParams(),
+      headers: new Headers(),
       body: blob,
       method: "POST",
     });
@@ -101,11 +106,23 @@ describe("RequestContext", () => {
     });
 
     const bodyData = { test: "data" };
+    const url = new URL(request.url);
+    const clonedReq = request.clone();
+    const body = clonedReq.body instanceof ReadableStream ? await clonedReq.json() : undefined;
+
+    const state = new MutableRequestState({
+      pathParams: {},
+      searchParams: url.searchParams,
+      body,
+      headers: new Headers(request.headers),
+    });
+
     const ctx = await RequestInputContext.fromRequest({
       request,
       method: "POST",
       path: "/api/test",
       pathParams: {},
+      state,
     });
 
     expect(ctx.path).toBe("/api/test");
@@ -131,6 +148,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: { test: "data" },
         method: "POST",
       });
@@ -143,6 +161,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: { test: "data" },
         inputSchema: validStringSchema,
         method: "POST",
@@ -158,6 +177,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: "test string",
         inputSchema: validStringSchema,
         method: "POST",
@@ -172,6 +192,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: 123, // Invalid for string schema
         inputSchema: invalidSchema,
         method: "POST",
@@ -185,6 +206,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: 123,
         inputSchema: invalidSchema,
         method: "POST",
@@ -213,6 +235,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: 123,
         inputSchema: invalidSchema,
         shouldValidateInput: false,
@@ -232,6 +255,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: formData,
         inputSchema: validStringSchema,
         method: "POST",
@@ -249,6 +273,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: blob,
         inputSchema: validStringSchema,
         method: "POST",
@@ -264,6 +289,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: null,
         inputSchema: validStringSchema,
         method: "POST",
@@ -278,6 +304,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         body: undefined,
         inputSchema: validStringSchema,
         method: "POST",
@@ -294,6 +321,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         inputSchema: validStringSchema,
         method: "POST",
         body: undefined,
@@ -308,6 +336,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         inputSchema: validStringSchema,
         shouldValidateInput: true,
         method: "POST",
@@ -322,6 +351,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         inputSchema: validStringSchema,
         shouldValidateInput: false,
         method: "POST",
@@ -346,6 +376,14 @@ describe("RequestContext", () => {
 
     test("Should pass through shouldValidateInput from fromRequest", async () => {
       const request = new Request("https://example.com/api/test");
+      const url = new URL(request.url);
+      const state = new MutableRequestState({
+        pathParams: {},
+        searchParams: url.searchParams,
+        body: undefined,
+        headers: new Headers(request.headers),
+      });
+
       const ctx = await RequestInputContext.fromRequest({
         request,
         path: "/test",
@@ -353,6 +391,7 @@ describe("RequestContext", () => {
         inputSchema: validStringSchema,
         shouldValidateInput: false,
         method: "POST",
+        state,
       });
 
       expect(ctx.input).toBeDefined();
@@ -365,6 +404,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         method: "POST",
         body: undefined,
       });
@@ -377,6 +417,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams: new URLSearchParams(),
+        headers: new Headers(),
         method: "POST",
         body: undefined,
       });
@@ -390,6 +431,7 @@ describe("RequestContext", () => {
         path: "/test",
         pathParams: {},
         searchParams,
+        headers: new Headers(),
         method: "POST",
         body: undefined,
       });
@@ -400,11 +442,20 @@ describe("RequestContext", () => {
 
     test("Should extract search params from request URL in fromRequest", async () => {
       const request = new Request("https://example.com/api/test?param=value");
+      const url = new URL(request.url);
+      const state = new MutableRequestState({
+        pathParams: {},
+        searchParams: url.searchParams,
+        body: undefined,
+        headers: new Headers(request.headers),
+      });
+
       const ctx = await RequestInputContext.fromRequest({
         request,
         path: "/test",
         pathParams: {},
         method: "POST",
+        state,
       });
 
       expect(ctx.query.get("param")).toBe("value");

package/src/api/request-input-context.ts

@@ -1,6 +1,7 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { ExtractPathParams } from "./internal/path";
 import { FragnoApiValidationError, type HTTPMethod } from "./api";
+import type { MutableRequestState } from "./mutable-request-state";
 
 export type RequestBodyType =
   | unknown // JSON
@@ -17,6 +18,7 @@ export class RequestInputContext<
   readonly #method: string;
   readonly #pathParams: ExtractPathParams<TPath>;
   readonly #searchParams: URLSearchParams;
+  readonly #headers: Headers;
   readonly #body: RequestBodyType;
   readonly #inputSchema: TInputSchema | undefined;
   readonly #shouldValidateInput: boolean;
@@ -26,6 +28,7 @@ export class RequestInputContext<
     method: string;
     pathParams: ExtractPathParams<TPath>;
     searchParams: URLSearchParams;
+    headers: Headers;
     body: RequestBodyType;
 
     request?: Request;
@@ -36,6 +39,7 @@ export class RequestInputContext<
     this.#method = config.method;
     this.#pathParams = config.pathParams;
     this.#searchParams = config.searchParams;
+    this.#headers = config.headers;
     this.#body = config.body;
     this.#inputSchema = config.inputSchema;
     this.#shouldValidateInput = config.shouldValidateInput ?? true;
@@ -54,22 +58,16 @@ export class RequestInputContext<
     pathParams: ExtractPathParams<TPath>;
     inputSchema?: TInputSchema;
     shouldValidateInput?: boolean;
+    state: MutableRequestState;
   }): Promise<RequestInputContext<TPath, TInputSchema>> {
-    const url = new URL(config.request.url);
-
-    // Clone the request to avoid consuming the body stream
-    // TODO: Probably we should just cache the result instead
-    const request = config.request.clone();
-
-    // TODO: Support other body types other than json
-    const json = request.body instanceof ReadableStream ? await request.json() : undefined;
-
+    // Use the mutable state (potentially modified by middleware)
     return new RequestInputContext({
       method: config.method,
       path: config.path,
-      pathParams: config.pathParams,
-      searchParams: url.searchParams,
-      body: json,
+      pathParams: config.state.pathParams as ExtractPathParams<TPath>,
+      searchParams: config.state.searchParams,
+      headers: config.state.headers,
+      body: config.state.body,
       inputSchema: config.inputSchema,
       shouldValidateInput: config.shouldValidateInput,
     });
@@ -88,12 +86,14 @@ export class RequestInputContext<
           path: TPath;
           pathParams: ExtractPathParams<TPath>;
           searchParams?: URLSearchParams;
+          headers?: Headers;
         }
       | {
           method: Exclude<HTTPMethod, "GET">;
           path: TPath;
           pathParams: ExtractPathParams<TPath>;
           searchParams?: URLSearchParams;
+          headers?: Headers;
           body: RequestBodyType;
           inputSchema?: TInputSchema;
         },
@@ -103,13 +103,13 @@ export class RequestInputContext<
       path: config.path,
       pathParams: config.pathParams,
       searchParams: config.searchParams ?? new URLSearchParams(),
+      headers: config.headers ?? new Headers(),
       body: "body" in config ? config.body : undefined,
       inputSchema: "inputSchema" in config ? config.inputSchema : undefined,
       shouldValidateInput: false, // No input validation in SSR context
     });
   }
 
-  // TODO(Wilco): We should support reading/modifying headers here.
   /**
    * The HTTP method as string (e.g., `GET`, `POST`)
    */
@@ -137,6 +137,13 @@ export class RequestInputContext<
   get query(): URLSearchParams {
     return this.#searchParams;
   }
+  /**
+   * [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) object for request headers
+   * @remarks `Headers`
+   */
+  get headers(): Headers {
+    return this.#headers;
+  }
   // TODO: Should probably remove this
   /**
    * @internal

package/src/api/request-middleware.test.ts

@@ -500,8 +500,7 @@ describe("Request Middleware", () => {
     });
   });
 
-  // TODO: This is not currently supported
-  test.todo("middleware can modify query parameters", async () => {
+  test("middleware can modify query parameters", async () => {
     const fragment = defineFragment("test-lib");
 
     const routes = [
@@ -542,4 +541,91 @@ describe("Request Middleware", () => {
       role: "some-other-role-defined-in-middleware",
     });
   });
+
+  test("middleware can modify request body", async () => {
+    const fragment = defineFragment("test-lib");
+
+    const routes = [
+      defineRoute({
+        method: "POST",
+        path: "/users",
+        inputSchema: z.object({ name: z.string(), role: z.string().optional() }),
+        outputSchema: z.object({ name: z.string(), role: z.string() }),
+        handler: async ({ input }, { json }) => {
+          const body = await input.valid();
+          return json({
+            name: body.name,
+            role: body.role ?? "user",
+          });
+        },
+      }),
+    ] as const;
+
+    const instance = createFragment(fragment, {}, routes, {
+      mountRoute: "/api",
+    }).withMiddleware(async ({ ifMatchesRoute, requestState }) => {
+      // Middleware modifies the request body
+      const result = await ifMatchesRoute("POST", "/users", async ({ input }) => {
+        const body = await input.valid();
+        // Modify the body by adding a role field
+        requestState.setBody({
+          ...body,
+          role: "admin-from-middleware",
+        });
+      });
+
+      return result;
+    });
+
+    const req = new Request("http://localhost/api/users", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "John Doe" }),
+    });
+
+    const res = await instance.handler(req);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      name: "John Doe",
+      role: "admin-from-middleware",
+    });
+  });
+
+  test("middleware can modify request headers", async () => {
+    const fragment = defineFragment("test-lib");
+
+    const routes = [
+      defineRoute({
+        method: "GET",
+        path: "/data",
+        outputSchema: z.object({ auth: z.string(), custom: z.string() }),
+        handler: async ({ headers }, { json }) => {
+          return json({
+            auth: headers.get("Authorization") ?? "none",
+            custom: headers.get("X-Custom-Header") ?? "none",
+          });
+        },
+      }),
+    ] as const;
+
+    const instance = createFragment(fragment, {}, routes, {
+      mountRoute: "/api",
+    }).withMiddleware(async ({ headers }) => {
+      // Middleware modifies headers
+      headers.set("Authorization", "Bearer middleware-token");
+      headers.set("X-Custom-Header", "middleware-value");
+      return undefined;
+    });
+
+    const req = new Request("http://localhost/api/data", {
+      method: "GET",
+    });
+
+    const res = await instance.handler(req);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      auth: "Bearer middleware-token",
+      custom: "middleware-value",
+    });
+  });
 });

package/src/api/request-middleware.ts

@@ -2,10 +2,10 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { ExtractRouteByPath, ExtractRoutePath } from "../client/client";
 import type { HTTPMethod } from "./api";
 import type { ExtractPathParams } from "./internal/path";
-import type { RequestBodyType } from "./request-input-context";
 import type { AnyFragnoRouteConfig } from "./route";
 import { RequestInputContext } from "./request-input-context";
 import { OutputContext, RequestOutputContext } from "./request-output-context";
+import { MutableRequestState } from "./mutable-request-state";
 
 export type FragnoMiddlewareCallback<
   TRoutes extends readonly AnyFragnoRouteConfig[],
@@ -19,10 +19,8 @@ export type FragnoMiddlewareCallback<
 export interface RequestMiddlewareOptions {
   path: string;
   method: HTTPMethod;
-  pathParams?: Record<string, string>;
-  searchParams: URLSearchParams;
-  body: RequestBodyType;
   request: Request;
+  state: MutableRequestState;
 }
 
 export class RequestMiddlewareOutputContext<
@@ -50,9 +48,11 @@ export class RequestMiddlewareOutputContext<
 export class RequestMiddlewareInputContext<const TRoutes extends readonly AnyFragnoRouteConfig[]> {
   readonly #options: RequestMiddlewareOptions;
   readonly #route: TRoutes[number];
+  readonly #state: MutableRequestState;
 
   constructor(routes: TRoutes, options: RequestMiddlewareOptions) {
     this.#options = options;
+    this.#state = options.state;
 
     const route = routes.find(
       (route) => route.path === options.path && route.method === options.method,
@@ -74,11 +74,15 @@ export class RequestMiddlewareInputContext<const TRoutes extends readonly AnyFra
   }
 
   get pathParams(): Record<string, string> {
-    return this.#options.pathParams ?? {};
+    return this.#state.pathParams;
   }
 
   get queryParams(): URLSearchParams {
-    return this.#options.searchParams;
+    return this.#state.searchParams;
+  }
+
+  get headers(): Headers {
+    return this.#state.headers;
   }
 
   get inputSchema(): StandardSchemaV1 | undefined {
@@ -89,6 +93,23 @@ export class RequestMiddlewareInputContext<const TRoutes extends readonly AnyFra
     return this.#route.outputSchema;
   }
 
+  /**
+   * Access to the mutable request state.
+   * Use this to modify query parameters, path parameters, or request body.
+   *
+   * @example
+   * ```typescript
+   * // Modify body
+   * requestState.setBody({ modified: true });
+   *
+   * // Query params are already accessible via queryParams getter
+   * // Path params are already accessible via pathParams getter
+   * ```
+   */
+  get requestState(): MutableRequestState {
+    return this.#state;
+  }
+
   // Defined as a field so that `this` reference stays in tact when destructuring
   ifMatchesRoute = async <
     const TMethod extends HTTPMethod,
@@ -116,6 +137,7 @@ export class RequestMiddlewareInputContext<const TRoutes extends readonly AnyFra
       path: path,
       pathParams: this.pathParams as ExtractPathParams<TPath>,
       inputSchema: this.#route.inputSchema,
+      state: this.#state,
     });
 
     const outputContext = new RequestOutputContext(this.#route.outputSchema);

package/src/api/request-output-context.test.ts

@@ -327,7 +327,9 @@ describe("RequestOutputContext", () => {
       try {
         while (true) {
           const { done, value } = await reader.read();
-          if (done) break;
+          if (done) {
+            break;
+          }
           chunks.push(decoder.decode(value));
         }
       } catch {
@@ -354,7 +356,9 @@ describe("RequestOutputContext", () => {
       try {
         while (true) {
           const { done, value } = await reader.read();
-          if (done) break;
+          if (done) {
+            break;
+          }
           chunks.push(decoder.decode(value));
         }
       } catch {