@fragno-dev/core 0.1.4 → 0.1.6

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

@@ -19,7 +19,8 @@ export class RequestInputContext<
   readonly #pathParams: ExtractPathParams<TPath>;
   readonly #searchParams: URLSearchParams;
   readonly #headers: Headers;
-  readonly #body: RequestBodyType;
+  readonly #body: string | undefined;
+  readonly #parsedBody: RequestBodyType;
   readonly #inputSchema: TInputSchema | undefined;
   readonly #shouldValidateInput: boolean;
 
@@ -28,9 +29,9 @@ export class RequestInputContext<
     method: string;
     pathParams: ExtractPathParams<TPath>;
     searchParams: URLSearchParams;
+    parsedBody: RequestBodyType;
+    rawBody?: string;
     headers: Headers;
-    body: RequestBodyType;
-
     request?: Request;
     inputSchema?: TInputSchema;
     shouldValidateInput?: boolean;
@@ -40,7 +41,8 @@ export class RequestInputContext<
     this.#pathParams = config.pathParams;
     this.#searchParams = config.searchParams;
     this.#headers = config.headers;
-    this.#body = config.body;
+    this.#body = config.rawBody;
+    this.#parsedBody = config.parsedBody;
     this.#inputSchema = config.inputSchema;
     this.#shouldValidateInput = config.shouldValidateInput ?? true;
   }
@@ -59,6 +61,7 @@ export class RequestInputContext<
     inputSchema?: TInputSchema;
     shouldValidateInput?: boolean;
     state: MutableRequestState;
+    rawBody?: string;
   }): Promise<RequestInputContext<TPath, TInputSchema>> {
     // Use the mutable state (potentially modified by middleware)
     return new RequestInputContext({
@@ -67,7 +70,8 @@ export class RequestInputContext<
       pathParams: config.state.pathParams as ExtractPathParams<TPath>,
       searchParams: config.state.searchParams,
       headers: config.state.headers,
-      body: config.state.body,
+      parsedBody: config.state.body,
+      rawBody: config.rawBody,
       inputSchema: config.inputSchema,
       shouldValidateInput: config.shouldValidateInput,
     });
@@ -104,7 +108,7 @@ export class RequestInputContext<
       pathParams: config.pathParams,
       searchParams: config.searchParams ?? new URLSearchParams(),
       headers: config.headers ?? new Headers(),
-      body: "body" in config ? config.body : undefined,
+      parsedBody: "body" in config ? config.body : undefined,
       inputSchema: "inputSchema" in config ? config.inputSchema : undefined,
       shouldValidateInput: false, // No input validation in SSR context
     });
@@ -144,13 +148,11 @@ export class RequestInputContext<
   get headers(): Headers {
     return this.#headers;
   }
-  // TODO: Should probably remove this
-  /**
-   * @internal
-   */
-  get rawBody(): RequestBodyType {
+
+  get rawBody(): string | undefined {
     return this.#body;
   }
+
   /**
    * Input validation context (only if inputSchema is defined)
    * @remarks `InputContext`
@@ -175,7 +177,7 @@ export class RequestInputContext<
       valid: async () => {
         if (!this.#shouldValidateInput) {
           // In SSR context, return the body directly without validation
-          return this.#body;
+          return this.#parsedBody;
         }
 
         return this.#validateInput();
@@ -191,11 +193,11 @@ export class RequestInputContext<
       throw new Error("No input schema defined for this route");
     }
 
-    if (this.#body instanceof FormData || this.#body instanceof Blob) {
+    if (this.#parsedBody instanceof FormData || this.#parsedBody instanceof Blob) {
       throw new Error("Schema validation is only supported for JSON data, not FormData or Blob");
     }
 
-    const result = await this.#inputSchema["~standard"].validate(this.#body);
+    const result = await this.#inputSchema["~standard"].validate(this.#parsedBody);
 
     if (result.issues) {
       throw new FragnoApiValidationError("Validation failed", result.issues);

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

@@ -53,8 +53,8 @@ describe("RequestOutputContext", () => {
       expect(response).toBeInstanceOf(Response);
       expect(response.status).toBe(201);
 
-      const body = await response.json();
-      expect(body).toBe(null);
+      const body = await response.text();
+      expect(body).toBe("");
     });
 
     test("Should return empty response with custom status number", async () => {
@@ -63,8 +63,8 @@ describe("RequestOutputContext", () => {
 
       expect(response.status).toBe(204);
 
-      const body = await response.json();
-      expect(body).toBe(null);
+      const body = await response.text();
+      expect(body).toBe("");
     });
 
     test("Should return empty response with custom headers via second parameter", async () => {
@@ -75,8 +75,8 @@ describe("RequestOutputContext", () => {
       expect(response.status).toBe(201);
       expect(response.headers.get("X-Custom")).toBe("test-value");
 
-      const body = await response.json();
-      expect(body).toBe(null);
+      const body = await response.text();
+      expect(body).toBe("");
     });
 
     test("Should return empty response with status and headers via second parameter", async () => {
@@ -87,8 +87,8 @@ describe("RequestOutputContext", () => {
       expect(response.status).toBe(204);
       expect(response.headers.get("X-Custom")).toBe("test-value");
 
-      const body = await response.json();
-      expect(body).toBe(null);
+      const body = await response.text();
+      expect(body).toBe("");
     });
 
     test("Should return empty response with ResponseInit object", async () => {
@@ -103,8 +103,8 @@ describe("RequestOutputContext", () => {
       expect(response.status).toBe(204);
       expect(response.headers.get("X-Custom")).toBe("test-value");
 
-      const body = await response.json();
-      expect(body).toBe(null);
+      const body = await response.text();
+      expect(body).toBe("");
     });
 
     test("Should handle multiple headers in ResponseInit", async () => {

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

@@ -75,7 +75,7 @@ export abstract class OutputContext<const TOutput, const TErrorCode extends stri
 
     if (typeof initOrStatus === "undefined") {
       const mergedHeaders = mergeHeaders(defaultHeaders, headers);
-      return Response.json(null, {
+      return new Response(null, {
         status: 201,
         headers: mergedHeaders,
       });
@@ -83,14 +83,14 @@ export abstract class OutputContext<const TOutput, const TErrorCode extends stri
 
     if (typeof initOrStatus === "number") {
       const mergedHeaders = mergeHeaders(defaultHeaders, headers);
-      return Response.json(null, {
+      return new Response(null, {
         status: initOrStatus,
         headers: mergedHeaders,
       });
     }
 
     const mergedHeaders = mergeHeaders(defaultHeaders, initOrStatus.headers, headers);
-    return Response.json(null, {
+    return new Response(null, {
       status: initOrStatus.status,
       headers: mergedHeaders,
     });

package/src/api/route-handler-input-options.ts

@@ -0,0 +1,15 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { ExtractPathParams } from "./internal/path";
+import type { InferOr } from "../util/types-util";
+
+/**
+ * Options for calling a route handler
+ */
+export type RouteHandlerInputOptions<
+  TPath extends string,
+  TInputSchema extends StandardSchemaV1 | undefined,
+> = {
+  pathParams?: ExtractPathParams<TPath>;
+  query?: URLSearchParams | Record<string, string>;
+  headers?: Headers | Record<string, string>;
+} & (TInputSchema extends undefined ? { body?: never } : { body: InferOr<TInputSchema, unknown> });

package/src/client/client.test.ts

@@ -1688,3 +1688,267 @@ describe("type guards", () => {
     expect(isGetHook(Symbol("fragno-get-hook"))).toBe(false);
   });
 });
+
+describe("Custom Fetcher Configuration", () => {
+  const testFragment = defineFragment("test-fragment");
+  const testRoutes = [
+    defineRoute({
+      method: "GET",
+      path: "/users",
+      outputSchema: z.array(z.object({ id: z.number(), name: z.string() })),
+      handler: async (_ctx, { json }) => json([{ id: 1, name: "John" }]),
+    }),
+    defineRoute({
+      method: "POST",
+      path: "/users",
+      inputSchema: z.object({ name: z.string() }),
+      outputSchema: z.object({ id: z.number(), name: z.string() }),
+      handler: async (_ctx, { json }) => json({ id: 2, name: "Jane" }),
+    }),
+  ] as const;
+
+  const clientConfig: FragnoPublicClientConfig = {
+    baseUrl: "http://localhost:3000",
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    (global.fetch as ReturnType<typeof vi.fn>).mockReset();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("fragment author sets RequestInit options (credentials)", async () => {
+    let capturedOptions: RequestInit | undefined;
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(async (_url, options) => {
+      capturedOptions = options;
+      return {
+        headers: new Headers(),
+        ok: true,
+        json: async () => [{ id: 1, name: "John" }],
+      } as Response;
+    });
+
+    const client = createClientBuilder(testFragment, clientConfig, testRoutes, {
+      type: "options",
+      options: { credentials: "include" },
+    });
+
+    const useUsers = client.createHook("/users");
+    await useUsers.query();
+
+    expect(capturedOptions).toBeDefined();
+    expect(capturedOptions?.credentials).toBe("include");
+  });
+
+  test("user overrides with their own RequestInit (deep merge)", async () => {
+    let capturedOptions: RequestInit | undefined;
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(async (_url, options) => {
+      capturedOptions = options;
+      return {
+        headers: new Headers(),
+        ok: true,
+        json: async () => [{ id: 1, name: "John" }],
+      } as Response;
+    });
+
+    const authorConfig = { type: "options", options: { credentials: "include" } } as const;
+    const userConfig = {
+      ...clientConfig,
+      fetcherConfig: { type: "options", options: { mode: "cors" } } as const,
+    };
+
+    const client = createClientBuilder(testFragment, userConfig, testRoutes, authorConfig);
+
+    const useUsers = client.createHook("/users");
+    await useUsers.query();
+
+    expect(capturedOptions).toBeDefined();
+    expect(capturedOptions?.credentials).toBe("include");
+    expect(capturedOptions?.mode).toBe("cors");
+  });
+
+  test("user provides custom fetch function (takes full precedence)", async () => {
+    const customFetch = vi.fn(async () => ({
+      headers: new Headers(),
+      ok: true,
+      json: async () => [{ id: 999, name: "Custom" }],
+    })) as unknown as typeof fetch;
+
+    const authorConfig = { type: "options", options: { credentials: "include" } } as const;
+    const userConfig = {
+      ...clientConfig,
+      fetcherConfig: { type: "function", fetcher: customFetch } as const,
+    };
+
+    const client = createClientBuilder(testFragment, userConfig, testRoutes, authorConfig);
+
+    const useUsers = client.createHook("/users");
+    const result = await useUsers.query();
+
+    expect(customFetch).toHaveBeenCalled();
+    expect(result).toEqual([{ id: 999, name: "Custom" }]);
+  });
+
+  test("author provides custom fetch, user provides RequestInit (user RequestInit used)", async () => {
+    const authorFetch = vi.fn(async () => ({
+      headers: new Headers(),
+      ok: true,
+      json: async () => [{ id: 777, name: "Author" }],
+    })) as unknown as typeof fetch;
+
+    let capturedOptions: RequestInit | undefined;
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(async (_url, options) => {
+      capturedOptions = options;
+      return {
+        headers: new Headers(),
+        ok: true,
+        json: async () => [{ id: 1, name: "John" }],
+      } as Response;
+    });
+
+    const authorConfig = { type: "function", fetcher: authorFetch } as const;
+    const userConfig = {
+      ...clientConfig,
+      fetcherConfig: { type: "options", options: { credentials: "include" } } as const,
+    };
+
+    const client = createClientBuilder(testFragment, userConfig, testRoutes, authorConfig);
+
+    const useUsers = client.createHook("/users");
+    await useUsers.query();
+
+    // User's RequestInit takes precedence, so global fetch should be used
+    expect(authorFetch).not.toHaveBeenCalled();
+    expect(global.fetch).toHaveBeenCalled();
+    expect(capturedOptions?.credentials).toBe("include");
+  });
+
+  test("headers merge correctly (user headers override author headers)", async () => {
+    let capturedOptions: RequestInit | undefined;
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(async (_url, options) => {
+      capturedOptions = options;
+      return {
+        headers: new Headers(),
+        ok: true,
+        json: async () => [{ id: 1, name: "John" }],
+      } as Response;
+    });
+
+    const authorConfig = {
+      type: "options",
+      options: {
+        headers: {
+          "X-Author-Header": "author-value",
+          "X-Shared-Header": "author-shared",
+        },
+      },
+    } as const;
+
+    const userConfig = {
+      ...clientConfig,
+      fetcherConfig: {
+        type: "options",
+        options: {
+          headers: {
+            "X-User-Header": "user-value",
+            "X-Shared-Header": "user-shared",
+          },
+        },
+      } as const,
+    };
+
+    const client = createClientBuilder(testFragment, userConfig, testRoutes, authorConfig);
+
+    const useUsers = client.createHook("/users");
+    await useUsers.query();
+
+    expect(capturedOptions).toBeDefined();
+    const headers = new Headers(capturedOptions?.headers);
+    expect(headers.get("X-Author-Header")).toBe("author-value");
+    expect(headers.get("X-User-Header")).toBe("user-value");
+    expect(headers.get("X-Shared-Header")).toBe("user-shared"); // User overrides
+  });
+
+  test("custom fetcher works with mutators", async () => {
+    let capturedOptions: RequestInit | undefined;
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(async (_url, options) => {
+      capturedOptions = options;
+      return {
+        headers: new Headers(),
+        ok: true,
+        status: 200,
+        json: async () => ({ id: 2, name: "Jane" }),
+      } as Response;
+    });
+
+    const client = createClientBuilder(testFragment, clientConfig, testRoutes, {
+      type: "options",
+      options: { credentials: "include" },
+    });
+
+    const mutator = client.createMutator("POST", "/users");
+    await mutator.mutateQuery({ body: { name: "Jane" } });
+
+    expect(capturedOptions).toBeDefined();
+    expect(capturedOptions?.credentials).toBe("include");
+    expect(capturedOptions?.method).toBe("POST");
+  });
+
+  test("buildUrl method works correctly", () => {
+    const client = createClientBuilder(testFragment, clientConfig, testRoutes);
+
+    const url1 = client.buildUrl("/users");
+    expect(url1).toBe("http://localhost:3000/api/test-fragment/users");
+
+    const url2 = client.buildUrl("/users/:id", { path: { id: "123" } });
+    expect(url2).toBe("http://localhost:3000/api/test-fragment/users/123");
+
+    const url3 = client.buildUrl("/users", { query: { sort: "name", order: "asc" } });
+    expect(url3).toBe("http://localhost:3000/api/test-fragment/users?sort=name&order=asc");
+
+    const url4 = client.buildUrl("/users/:id", {
+      path: { id: "456" },
+      query: { include: "posts" },
+    });
+    expect(url4).toBe("http://localhost:3000/api/test-fragment/users/456?include=posts");
+  });
+
+  test("getFetcher returns correct fetcher and options", () => {
+    const customFetch = vi.fn() as unknown as typeof fetch;
+    const client = createClientBuilder(
+      testFragment,
+      {
+        ...clientConfig,
+        fetcherConfig: { type: "function", fetcher: customFetch },
+      },
+      testRoutes,
+    );
+
+    const { fetcher, defaultOptions } = client.getFetcher();
+    expect(fetcher).toBe(customFetch);
+    expect(defaultOptions).toBeUndefined();
+  });
+
+  test("getFetcher returns default fetch and options", () => {
+    const client = createClientBuilder(
+      testFragment,
+      {
+        ...clientConfig,
+        fetcherConfig: { type: "options", options: { credentials: "include" } },
+      },
+      testRoutes,
+    );
+
+    const { fetcher, defaultOptions } = client.getFetcher();
+    expect(fetcher).toBe(fetch);
+    expect(defaultOptions).toBeDefined();
+    expect(defaultOptions?.credentials).toBe("include");
+  });
+});

package/src/client/client.ts

@@ -13,6 +13,7 @@ import { getMountRoute } from "../api/internal/route";
 import { RequestInputContext } from "../api/request-input-context";
 import { RequestOutputContext } from "../api/request-output-context";
 import type {
+  FetcherConfig,
   FragnoFragmentSharedConfig,
   FragnoPublicClientConfig,
 } from "../api/fragment-instantiation";
@@ -31,6 +32,7 @@ import {
   type FlattenRouteFactories,
   resolveRouteFactories,
 } from "../api/route";
+import { mergeFetcherConfigs } from "./internal/fetcher-merge";
 
 /**
  * Symbols used to identify hook types
@@ -487,6 +489,7 @@ export class ClientBuilder<
 > {
   #publicConfig: FragnoPublicClientConfig;
   #fragmentConfig: TFragmentConfig;
+  #fetcherConfig?: FetcherConfig;
 
   #cache = new Map<string, CacheLine>();
 
@@ -497,6 +500,7 @@ export class ClientBuilder<
   constructor(publicConfig: FragnoPublicClientConfig, fragmentConfig: TFragmentConfig) {
     this.#publicConfig = publicConfig;
     this.#fragmentConfig = fragmentConfig;
+    this.#fetcherConfig = publicConfig.fetcherConfig;
 
     const [createFetcherStore, createMutatorStore, { invalidateKeys }] = nanoquery({
       cache: this.#cache,
@@ -514,6 +518,54 @@ export class ClientBuilder<
     return { obj: obj, [STORE_SYMBOL]: true };
   }
 
+  /**
+   * Build a URL for a custom backend call using the configured baseUrl and mountRoute.
+   * Useful for fragment authors who need to make custom fetch calls.
+   */
+  buildUrl<TPath extends string>(
+    path: TPath,
+    params?: {
+      path?: MaybeExtractPathParamsOrWiden<TPath, string>;
+      query?: Record<string, string>;
+    },
+  ): string {
+    const baseUrl = this.#publicConfig.baseUrl ?? "";
+    const mountRoute = getMountRoute(this.#fragmentConfig);
+
+    return buildUrl(
+      { baseUrl, mountRoute, path },
+      { pathParams: params?.path, queryParams: params?.query },
+    );
+  }
+
+  /**
+   * Get the configured fetcher function for custom backend calls.
+   * Returns fetch with merged options applied.
+   */
+  getFetcher(): {
+    fetcher: typeof fetch;
+    defaultOptions: RequestInit | undefined;
+  } {
+    return {
+      fetcher: this.#getFetcher(),
+      defaultOptions: this.#getFetcherOptions(),
+    };
+  }
+
+  #getFetcher(): typeof fetch {
+    if (this.#fetcherConfig?.type === "function") {
+      return this.#fetcherConfig.fetcher;
+    }
+    return fetch;
+  }
+
+  #getFetcherOptions(): RequestInit | undefined {
+    if (this.#fetcherConfig?.type === "options") {
+      return this.#fetcherConfig.options;
+    }
+    return undefined;
+  }
+
   createHook<TPath extends ExtractGetRoutePaths<TFragmentConfig["routes"]>>(
     path: ValidateGetRoutePath<TFragmentConfig["routes"], TPath>,
     options?: CreateHookOptions,
@@ -611,6 +663,8 @@ export class ClientBuilder<
 
     const baseUrl = this.#publicConfig.baseUrl ?? "";
     const mountRoute = getMountRoute(this.#fragmentConfig);
+    const fetcher = this.#getFetcher();
+    const fetcherOptions = this.#getFetcherOptions();
 
     async function callServerSideHandler(params: {
       pathParams?: Record<string, string | ReadableAtom<string>>;
@@ -650,7 +704,7 @@ export class ClientBuilder<
 
       let response: Response;
       try {
-        response = await fetch(url);
+        response = fetcherOptions ? await fetcher(url, fetcherOptions) : await fetcher(url);
       } catch (error) {
         throw FragnoClientFetchError.fromUnknownFetchError(error);
       }
@@ -795,6 +849,8 @@ export class ClientBuilder<
 
     const baseUrl = this.#publicConfig.baseUrl ?? "";
     const mountRoute = getMountRoute(this.#fragmentConfig);
+    const fetcher = this.#getFetcher();
+    const fetcherOptions = this.#getFetcherOptions();
 
     async function executeMutateQuery({
       body,
@@ -828,10 +884,12 @@ export class ClientBuilder<
 
       let response: Response;
       try {
-        response = await fetch(url, {
+        const requestOptions: RequestInit = {
+          ...fetcherOptions,
           method,
           body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
+        };
+        response = await fetcher(url, requestOptions);
       } catch (error) {
         throw FragnoClientFetchError.fromUnknownFetchError(error);
       }
@@ -1008,6 +1066,7 @@ export function createClientBuilder<
   },
   publicConfig: FragnoPublicClientConfig,
   routesOrFactories: TRoutesOrFactories,
+  authorFetcherConfig?: FetcherConfig,
 ): ClientBuilder<
   FlattenRouteFactories<TRoutesOrFactories>,
   FragnoFragmentSharedConfig<FlattenRouteFactories<TRoutesOrFactories>>
@@ -1030,12 +1089,15 @@ export function createClientBuilder<
   };
 
   const mountRoute = publicConfig.mountRoute ?? `/${definition.name}`;
+  const mergedFetcherConfig = mergeFetcherConfigs(authorFetcherConfig, publicConfig.fetcherConfig);
   const fullPublicConfig = {
     ...publicConfig,
     mountRoute,
+    fetcherConfig: mergedFetcherConfig,
   };
 
   return new ClientBuilder(fullPublicConfig, fragmentConfig);
 }
 
 export * from "./client-error";
+export type { FetcherConfig };

package/src/client/internal/fetcher-merge.ts

@@ -0,0 +1,59 @@
+import type { FetcherConfig } from "../../api/fragment-instantiation";
+
+/**
+ * Merge two fetcher configurations, with user config taking precedence.
+ * If user provides a custom function, it takes full precedence.
+ * Otherwise, deep merge RequestInit options.
+ */
+export function mergeFetcherConfigs(
+  authorConfig?: FetcherConfig,
+  userConfig?: FetcherConfig,
+): FetcherConfig | undefined {
+  // If user provides custom function, it takes full precedence
+  if (userConfig?.type === "function") {
+    return userConfig;
+  }
+
+  if (!userConfig && authorConfig?.type === "function") {
+    return authorConfig;
+  }
+
+  // Deep merge RequestInit options
+  const authorOpts = authorConfig?.type === "options" ? authorConfig.options : {};
+  const userOpts = userConfig?.type === "options" ? userConfig.options : {};
+
+  // If both are empty, return undefined
+  if (Object.keys(authorOpts).length === 0 && Object.keys(userOpts).length === 0) {
+    return undefined;
+  }
+
+  return {
+    type: "options",
+    options: {
+      ...authorOpts,
+      ...userOpts,
+      headers: mergeHeaders(authorOpts.headers, userOpts.headers),
+    },
+  };
+}
+
+/**
+ * Merge headers from author and user configs.
+ * User headers override author headers.
+ */
+function mergeHeaders(author?: HeadersInit, user?: HeadersInit): HeadersInit | undefined {
+  if (!author && !user) {
+    return undefined;
+  }
+
+  // Convert to Headers objects and merge
+  const merged = new Headers(author);
+  new Headers(user).forEach((value, key) => merged.set(key, value));
+
+  // If no headers after merge, return undefined
+  if (merged.keys().next().done) {
+    return undefined;
+  }
+
+  return merged;
+}