@fragno-dev/core 0.1.11 → 0.2.2

package/src/api/fragment-services.test.ts

@@ -1,4 +1,5 @@
 import { describe, test, expect, expectTypeOf } from "vitest";
+
 import { defineFragment } from "./fragment-definition-builder";
 import { instantiate } from "./fragment-instantiator";
 

package/src/api/internal/path-runtime.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "vitest";
+
 import { buildPath, extractPathParams, matchPathParams } from "./path";
 
 describe("extractPathParams (runtime names)", () => {
@@ -77,6 +78,13 @@ describe("matchPathParams (runtime extraction)", () => {
     expect(matchPathParams("/users/:id", "/users/123/")).toEqual({ id: "123" });
   });
 
+  test("URL decodes named params", () => {
+    expect(matchPathParams("/users/:name", "/users/a%20b")).toEqual({ name: "a b" });
+    expect(matchPathParams("/files/:path", "/files/folder%2Fsubfolder")).toEqual({
+      path: "folder/subfolder",
+    });
+  });
+
   test("pattern longer than path fills empty strings for remaining params", () => {
     // Remaining ":id" becomes empty string
     expect(matchPathParams("/users/:id", "/users")).toEqual({ id: "" });

package/src/api/internal/path-type.test.ts

@@ -1,4 +1,7 @@
 import { test, expect, expectTypeOf } from "vitest";
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import type {
   ExtractPathParams,
   ExtractPathParamNames,
@@ -9,7 +12,6 @@ import type {
   MaybeExtractPathParamsOrWiden,
   QueryParamsHint,
 } from "./path";
-import type { StandardSchemaV1 } from "@standard-schema/spec";
 
 // Type-only tests using expectTypeOf from vitest
 test("ExtractPathParams type tests", () => {

package/src/api/internal/route.test.ts

@@ -1,4 +1,5 @@
 import { test, expect } from "vitest";
+
 import { getMountRoute } from "./route";
 
 test("getMountRoute - default mount route", () => {

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

@@ -28,6 +28,13 @@ export class RequestContextStorage<TRequestStorage> {
     return this.#storage.run(data, callback);
   }
 
+  /**
+   * Check whether a store is currently active.
+   */
+  hasStore(): boolean {
+    return this.#storage.getStore() !== undefined;
+  }
+
   /**
    * Get the current stored data from AsyncLocalStorage.
    * @throws an error if called outside of a run() callback.

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

@@ -1,8 +1,10 @@
 import { test, expect, describe } from "vitest";
-import { RequestInputContext } from "./request-input-context";
-import { FragnoApiValidationError } from "./api";
+
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+import { FragnoApiValidationError } from "./api";
 import { MutableRequestState } from "./mutable-request-state";
+import { RequestInputContext } from "./request-input-context";
 
 // Mock schema implementations for testing
 const createMockSchema = (shouldPass: boolean, returnValue?: unknown): StandardSchemaV1 => ({
@@ -292,6 +294,29 @@ describe("RequestContext", () => {
       );
     });
 
+    test("Should throw error when trying to validate ReadableStream", async () => {
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode("stream body"));
+          controller.close();
+        },
+      });
+
+      const ctx = new RequestInputContext({
+        path: "/test",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: stream,
+        inputSchema: validStringSchema,
+        method: "POST",
+      });
+
+      await expect(ctx.input.valid()).rejects.toThrow(
+        "Schema validation is only supported for JSON data, not FormData, Blob, or ReadableStream",
+      );
+    });
+
     test("Should handle null body", async () => {
       const ctx = new RequestInputContext({
         path: "/test",
@@ -493,4 +518,133 @@ describe("RequestContext", () => {
       expect(ctx.query.get("ssr")).toBe("true");
     });
   });
+
+  describe("FormData handling", () => {
+    test("formData() should return FormData when body is FormData", () => {
+      const formData = new FormData();
+      formData.append("file", new Blob(["test"]), "test.txt");
+      formData.append("description", "A test file");
+
+      const ctx = new RequestInputContext({
+        path: "/upload",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: formData,
+        method: "POST",
+      });
+
+      const result = ctx.formData();
+      expect(result).toBe(formData);
+      expect(result.get("description")).toBe("A test file");
+    });
+
+    test("formData() should throw when body is not FormData", () => {
+      const ctx = new RequestInputContext({
+        path: "/upload",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: { key: "value" },
+        method: "POST",
+      });
+
+      expect(() => ctx.formData()).toThrow(
+        "Request body is not FormData. Ensure the request was sent with Content-Type: multipart/form-data.",
+      );
+    });
+
+    test("formData() should throw when body is undefined", () => {
+      const ctx = new RequestInputContext({
+        path: "/upload",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: undefined,
+        method: "POST",
+      });
+
+      expect(() => ctx.formData()).toThrow(
+        "Request body is not FormData. Ensure the request was sent with Content-Type: multipart/form-data.",
+      );
+    });
+
+    test("isFormData() should return true when body is FormData", () => {
+      const formData = new FormData();
+      formData.append("key", "value");
+
+      const ctx = new RequestInputContext({
+        path: "/upload",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: formData,
+        method: "POST",
+      });
+
+      expect(ctx.isFormData()).toBe(true);
+    });
+
+    test("isFormData() should return false when body is JSON", () => {
+      const ctx = new RequestInputContext({
+        path: "/upload",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: { key: "value" },
+        method: "POST",
+      });
+
+      expect(ctx.isFormData()).toBe(false);
+    });
+
+    test("isFormData() should return false when body is undefined", () => {
+      const ctx = new RequestInputContext({
+        path: "/upload",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: undefined,
+        method: "POST",
+      });
+
+      expect(ctx.isFormData()).toBe(false);
+    });
+
+    test("isFormData() should return false when body is Blob", () => {
+      const blob = new Blob(["test content"], { type: "text/plain" });
+
+      const ctx = new RequestInputContext({
+        path: "/upload",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: blob,
+        method: "POST",
+      });
+
+      expect(ctx.isFormData()).toBe(false);
+    });
+
+    test("Can use isFormData() to conditionally access formData()", () => {
+      const formData = new FormData();
+      formData.append("file", new Blob(["test"]), "test.txt");
+
+      const ctx = new RequestInputContext({
+        path: "/upload",
+        pathParams: {},
+        searchParams: new URLSearchParams(),
+        headers: new Headers(),
+        parsedBody: formData,
+        method: "POST",
+      });
+
+      if (ctx.isFormData()) {
+        const result = ctx.formData();
+        expect(result.get("file")).toBeInstanceOf(Blob);
+      } else {
+        expect.fail("Should have detected FormData");
+      }
+    });
+  });
 });

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

@@ -1,12 +1,14 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { ExtractPathParams } from "./internal/path";
+
 import { FragnoApiValidationError, type HTTPMethod } from "./api";
+import type { ExtractPathParams } from "./internal/path";
 import type { MutableRequestState } from "./mutable-request-state";
 
 export type RequestBodyType =
   | unknown // JSON
   | FormData
   | Blob
+  | ReadableStream<Uint8Array>
   | null
   | undefined;
 
@@ -153,6 +155,84 @@ export class RequestInputContext<
     return this.#body;
   }
 
+  /**
+   * Access the request body as FormData.
+   *
+   * Use this method when handling file uploads or multipart form submissions.
+   * The request must have been sent with Content-Type: multipart/form-data.
+   *
+   * @throws Error if the request body is not FormData
+   *
+   * @example
+   * ```typescript
+   * defineRoute({
+   *   method: "POST",
+   *   path: "/upload",
+   *   async handler(ctx, res) {
+   *     const formData = ctx.formData();
+   *     const file = formData.get("file") as File;
+   *     const description = formData.get("description") as string;
+   *     // ... process file
+   *   }
+   * });
+   * ```
+   */
+  formData(): FormData {
+    if (!(this.#parsedBody instanceof FormData)) {
+      throw new Error(
+        "Request body is not FormData. Ensure the request was sent with Content-Type: multipart/form-data.",
+      );
+    }
+    return this.#parsedBody;
+  }
+
+  /**
+   * Check if the request body is FormData.
+   *
+   * Useful for routes that accept both JSON and FormData payloads.
+   *
+   * @example
+   * ```typescript
+   * defineRoute({
+   *   method: "POST",
+   *   path: "/upload",
+   *   async handler(ctx, res) {
+   *     if (ctx.isFormData()) {
+   *       const formData = ctx.formData();
+   *       // handle file upload
+   *     } else {
+   *       const json = await ctx.input.valid();
+   *       // handle JSON payload
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  isFormData(): boolean {
+    return this.#parsedBody instanceof FormData;
+  }
+
+  /**
+   * Access the request body as a ReadableStream (application/octet-stream).
+   *
+   * @throws Error if the request body is not a ReadableStream
+   */
+  bodyStream(): ReadableStream<Uint8Array> {
+    if (!(this.#parsedBody instanceof ReadableStream)) {
+      throw new Error(
+        "Request body is not a ReadableStream. Ensure the request was sent with Content-Type: application/octet-stream.",
+      );
+    }
+    return this.#parsedBody;
+  }
+
+  /**
+   * Check if the request body is a ReadableStream.
+   */
+  isBodyStream(): boolean {
+    return this.#parsedBody instanceof ReadableStream;
+  }
+
   /**
    * Input validation context (only if inputSchema is defined)
    * @remarks `InputContext`
@@ -197,6 +277,12 @@ export class RequestInputContext<
       throw new Error("Schema validation is only supported for JSON data, not FormData or Blob");
     }
 
+    if (this.#parsedBody instanceof ReadableStream) {
+      throw new Error(
+        "Schema validation is only supported for JSON data, not FormData, Blob, or ReadableStream",
+      );
+    }
+
     const result = await this.#inputSchema["~standard"].validate(this.#parsedBody);
 
     if (result.issues) {

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

@@ -1,9 +1,11 @@
 import { test, expect, describe, expectTypeOf } from "vitest";
+
+import { z } from "zod";
+
+import { FragnoApiValidationError } from "./error";
 import { defineFragment } from "./fragment-definition-builder";
 import { instantiate } from "./fragment-instantiator";
 import { defineRoute } from "./route";
-import { z } from "zod";
-import { FragnoApiValidationError } from "./error";
 
 describe("Request Middleware", () => {
   test("middleware can intercept and return early", async () => {
@@ -276,6 +278,45 @@ describe("Request Middleware", () => {
     expect(middlewareCalled).toBe(true);
   });
 
+  test("ifMatchesRoute - supports internal routes", async () => {
+    const config = {};
+
+    const internalRoutes = [
+      defineRoute({
+        method: "GET",
+        path: "/status",
+        handler: async (_input, { json }) => {
+          return json({ ok: true });
+        },
+      }),
+    ] as const;
+
+    const definition = defineFragment<typeof config>("test-lib")
+      .withInternalRoutes(internalRoutes)
+      .build();
+
+    const instance = instantiate(definition)
+      .withConfig(config)
+      .withOptions({
+        mountRoute: "/api",
+      })
+      .build()
+      .withMiddleware(async ({ ifMatchesRoute }) => {
+        return await ifMatchesRoute("GET", "/_internal/status", async ({ path }, { json }) => {
+          expectTypeOf(path).toEqualTypeOf<"/_internal/status">();
+          return json({ ok: false }, 418);
+        });
+      });
+
+    const req = new Request("http://localhost/api/_internal/status", {
+      method: "GET",
+    });
+
+    const res = await instance.handler(req);
+    expect(res.status).toBe(418);
+    expect(await res.json()).toEqual({ ok: false });
+  });
+
   test("only one middleware is supported", async () => {
     const config = {};
 

package/src/api/request-middleware.ts

@@ -1,11 +1,12 @@
 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 { AnyFragnoRouteConfig } from "./route";
+import { MutableRequestState } from "./mutable-request-state";
 import { RequestInputContext } from "./request-input-context";
 import { OutputContext, RequestOutputContext } from "./request-output-context";
-import { MutableRequestState } from "./mutable-request-state";
+import type { AnyFragnoRouteConfig } from "./route";
 
 export type FragnoMiddlewareCallback<
   TRoutes extends readonly AnyFragnoRouteConfig[],
@@ -113,7 +114,7 @@ export class RequestMiddlewareInputContext<const TRoutes extends readonly AnyFra
   // Defined as a field so that `this` reference stays in tact when destructuring
   ifMatchesRoute = async <
     const TMethod extends HTTPMethod,
-    const TPath extends ExtractRoutePath<TRoutes>,
+    const TPath extends ExtractRoutePath<TRoutes, TMethod>,
     const TRoute extends ExtractRouteByPath<TRoutes, TPath, TMethod> = ExtractRouteByPath<
       TRoutes,
       TPath,

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

@@ -1,7 +1,9 @@
 import { test, expect, describe, vi } from "vitest";
-import { RequestOutputContext } from "./request-output-context";
+
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import { ResponseStream } from "./internal/response-stream";
+import { RequestOutputContext } from "./request-output-context";
 
 // Mock schema implementations for testing
 const createMockSchema = (shouldPass: boolean, returnValue?: unknown): StandardSchemaV1 => ({

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

@@ -1,7 +1,8 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import type { ContentlessStatusCode, StatusCode } from "../http/http-status";
-import { ResponseStream } from "./internal/response-stream";
 import type { InferOrUnknown } from "../util/types-util";
+import { ResponseStream } from "./internal/response-stream";
 
 export type ResponseData = string | ArrayBuffer | ReadableStream | Uint8Array<ArrayBuffer>;
 

package/src/api/route-caller.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, expectTypeOf, test } from "vitest";
+
+import { z } from "zod";
+
+import type { FragnoResponse } from "./fragno-response";
+import { defineRoute } from "./route";
+import { createRouteCaller } from "./route-caller";
+
+describe("createRouteCaller", () => {
+  test("replaces inherited content-type with application/json for object bodies", async () => {
+    let capturedRequest: Request | null = null;
+
+    const callRoute = createRouteCaller<{
+      callRoute: (
+        method: "POST",
+        path: "/test",
+        input: { body: { hello: string } },
+      ) => Promise<unknown>;
+    }>({
+      baseUrl: "https://example.com/app",
+      baseHeaders: {
+        "content-type": "application/x-www-form-urlencoded",
+      },
+      fetch: async (request) => {
+        capturedRequest = request;
+        return new Response(JSON.stringify({ ok: true }), {
+          headers: { "content-type": "application/json" },
+        });
+      },
+    });
+
+    await callRoute("POST", "/test", {
+      body: { hello: "world" },
+    });
+
+    if (!capturedRequest) {
+      throw new Error("Expected fetch to receive a request.");
+    }
+
+    const request = capturedRequest as Request;
+    expect(request.headers.get("content-type")).toBe("application/json");
+    expect(await request.text()).toBe('{"hello":"world"}');
+  });
+
+  test("keeps an explicit application/octet-stream content-type for binary bodies", async () => {
+    let capturedRequest: Request | null = null;
+
+    const callRoute = createRouteCaller<{
+      callRoute: (
+        method: "POST",
+        path: "/binary",
+        input: { body: ArrayBuffer; headers: HeadersInit },
+      ) => Promise<unknown>;
+    }>({
+      baseUrl: "https://example.com/app",
+      baseHeaders: {
+        "content-type": "multipart/form-data; boundary=---original",
+      },
+      fetch: async (request) => {
+        capturedRequest = request;
+        return new Response(JSON.stringify({ ok: true }), {
+          headers: { "content-type": "application/json" },
+        });
+      },
+    });
+
+    await callRoute("POST", "/binary", {
+      body: new Uint8Array([1, 2, 3]).buffer,
+      headers: {
+        "content-type": "application/octet-stream",
+      },
+    });
+
+    if (!capturedRequest) {
+      throw new Error("Expected fetch to receive a request.");
+    }
+
+    const request = capturedRequest as Request;
+    expect(request.headers.get("content-type")).toBe("application/octet-stream");
+    expect(new Uint8Array(await request.arrayBuffer())).toEqual(new Uint8Array([1, 2, 3]));
+  });
+
+  test("infers route-specific inputs and outputs from fragment routes", async () => {
+    const routes = [
+      defineRoute({
+        method: "GET",
+        path: "/threads",
+        outputSchema: z.object({
+          threads: z.array(z.object({ id: z.string() })),
+          hasNextPage: z.boolean(),
+        }),
+        handler: async (_ctx, { json }) =>
+          json({ threads: [{ id: "thread-1" }], hasNextPage: false }),
+      }),
+      defineRoute({
+        method: "GET",
+        path: "/threads/:threadId/messages",
+        outputSchema: z.object({
+          messages: z.array(z.object({ id: z.string(), threadId: z.string() })),
+          cursor: z.string().optional(),
+          hasNextPage: z.boolean(),
+        }),
+        handler: async ({ pathParams, query }, { json }) =>
+          json({
+            messages: [{ id: "message-1", threadId: pathParams.threadId }],
+            cursor: query.get("cursor") ?? undefined,
+            hasNextPage: false,
+          }),
+      }),
+      defineRoute({
+        method: "POST",
+        path: "/threads/:threadId/reply",
+        inputSchema: z.object({ text: z.string() }),
+        outputSchema: z.object({ ok: z.boolean() }),
+        handler: async (_ctx, { json }) => json({ ok: true }),
+      }),
+    ] as const;
+
+    type FakeFragment = {
+      routes: typeof routes;
+    };
+
+    const callRoute = createRouteCaller<FakeFragment>({
+      baseUrl: "https://example.com/app",
+      mountRoute: "/api",
+      fetch: async (request) => {
+        const url = new URL(request.url);
+
+        if (url.pathname === "/api/threads") {
+          return Response.json({
+            threads: [{ id: "thread-1" }],
+            hasNextPage: false,
+          });
+        }
+
+        if (url.pathname === "/api/threads/thread-1/messages") {
+          return Response.json({
+            messages: [{ id: "message-1", threadId: "thread-1" }],
+            cursor: url.searchParams.get("cursor") ?? undefined,
+            hasNextPage: false,
+          });
+        }
+
+        if (url.pathname === "/api/threads/thread-1/reply") {
+          const body = (await request.json()) as { text: string };
+          return Response.json({ ok: body.text === "hello" });
+        }
+
+        return Response.json({ message: "Not found", code: "NOT_FOUND" }, { status: 404 });
+      },
+    });
+
+    const listResponse = await callRoute("GET", "/threads", {
+      query: { cursor: "cursor-1" },
+    });
+    const messagesResponse = await callRoute("GET", "/threads/:threadId/messages", {
+      pathParams: { threadId: "thread-1" },
+      query: { cursor: "cursor-1" },
+    });
+    const replyResponse = await callRoute("POST", "/threads/:threadId/reply", {
+      pathParams: { threadId: "thread-1" },
+      body: { text: "hello" },
+    });
+
+    expectTypeOf<Extract<typeof listResponse, { type: "json" }>["data"]>().toEqualTypeOf<{
+      threads: { id: string }[];
+      hasNextPage: boolean;
+    }>();
+    expectTypeOf<Extract<typeof messagesResponse, { type: "json" }>["data"]>().toEqualTypeOf<{
+      messages: { id: string; threadId: string }[];
+      cursor?: string | undefined;
+      hasNextPage: boolean;
+    }>();
+    expectTypeOf<Extract<typeof replyResponse, { type: "json" }>["data"]>().toEqualTypeOf<{
+      ok: boolean;
+    }>();
+    expectTypeOf<typeof listResponse>().toExtend<FragnoResponse<unknown>>();
+
+    expect(listResponse.type).toBe("json");
+    if (listResponse.type === "json") {
+      expect(listResponse.data.threads[0]?.id).toBe("thread-1");
+    }
+
+    expect(messagesResponse.type).toBe("json");
+    if (messagesResponse.type === "json") {
+      expect(messagesResponse.data.messages[0]?.threadId).toBe("thread-1");
+      expect(messagesResponse.data.cursor).toBe("cursor-1");
+    }
+
+    expect(replyResponse.type).toBe("json");
+    if (replyResponse.type === "json") {
+      expect(replyResponse.data.ok).toBe(true);
+    }
+  });
+});