@fragno-dev/core 0.1.5 → 0.1.7

package/src/api/fragno-response.ts

@@ -0,0 +1,132 @@
+/**
+ * Discriminated union representing all possible Fragno response types
+ */
+export type FragnoResponse<T> =
+  | {
+      type: "empty";
+      status: number;
+      headers: Headers;
+    }
+  | {
+      type: "error";
+      status: number;
+      headers: Headers;
+      error: { message: string; code: string };
+    }
+  | {
+      type: "json";
+      status: number;
+      headers: Headers;
+      data: T;
+    }
+  | {
+      type: "jsonStream";
+      status: number;
+      headers: Headers;
+      stream: AsyncGenerator<T extends unknown[] ? T[number] : T>;
+    };
+
+/**
+ * Parse a Response object into a FragnoResponse discriminated union
+ */
+export async function parseFragnoResponse<T>(response: Response): Promise<FragnoResponse<T>> {
+  const status = response.status;
+  const headers = response.headers;
+  const contentType = headers.get("content-type") || "";
+
+  // Check for streaming response
+  if (contentType.includes("application/x-ndjson")) {
+    return {
+      type: "jsonStream",
+      status,
+      headers,
+      stream: parseNDJSONStream<T>(response),
+    };
+  }
+
+  // Parse JSON body
+  const text = await response.text();
+
+  // Empty response
+  if (!text || text === "null") {
+    return {
+      type: "empty",
+      status,
+      headers,
+    };
+  }
+
+  const data = JSON.parse(text);
+
+  // Error response (has message and code, or error and code)
+  if (data && typeof data === "object" && "code" in data) {
+    if ("message" in data) {
+      return {
+        type: "error",
+        status,
+        headers,
+        error: { message: data.message, code: data.code },
+      };
+    }
+    if ("error" in data) {
+      return {
+        type: "error",
+        status,
+        headers,
+        error: { message: data.error, code: data.code },
+      };
+    }
+  }
+
+  // JSON response
+  return {
+    type: "json",
+    status,
+    headers,
+    data: data as T,
+  };
+}
+
+/**
+ * Parse an NDJSON stream into an async generator
+ */
+async function* parseNDJSONStream<T>(
+  response: Response,
+): AsyncGenerator<T extends unknown[] ? T[number] : T> {
+  if (!response.body) {
+    return;
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (done) {
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+
+      // Keep the last incomplete line in the buffer
+      buffer = lines.pop() || "";
+
+      for (const line of lines) {
+        if (line.trim()) {
+          yield JSON.parse(line) as T extends unknown[] ? T[number] : T;
+        }
+      }
+    }
+
+    // Process any remaining data in the buffer
+    if (buffer.trim()) {
+      yield JSON.parse(buffer) as T extends unknown[] ? T[number] : T;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

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

@@ -446,39 +446,39 @@ test("MaybeExtractPathParamsOrWiden type tests", () => {
 test("QueryParamsHint type tests", () => {
   // Basic usage with string union
   expectTypeOf<QueryParamsHint<"page" | "limit">>().toEqualTypeOf<
-    Partial<Record<"page" | "limit", string>> & Record<string, string>
+    Partial<Record<"page" | "limit", string>> & Record<string, string | undefined>
   >();
 
   // Single parameter hint
   expectTypeOf<QueryParamsHint<"search">>().toEqualTypeOf<
-    Partial<Record<"search", string>> & Record<string, string>
+    Partial<Record<"search", string>> & Record<string, string | undefined>
   >();
 
   // Empty hint (never) - should still allow any string keys
   expectTypeOf<QueryParamsHint<never>>().toEqualTypeOf<
-    Partial<Record<never, string>> & Record<string, string>
+    Partial<Record<never, string>> & Record<string, string | undefined>
   >();
 
   // With custom value type
   expectTypeOf<QueryParamsHint<"page" | "limit", number>>().toEqualTypeOf<
-    Partial<Record<"page" | "limit", number>> & Record<string, number>
+    Partial<Record<"page" | "limit", number>> & Record<string, number | undefined>
   >();
 
   // With boolean value type
   expectTypeOf<QueryParamsHint<"enabled" | "debug", boolean>>().toEqualTypeOf<
-    Partial<Record<"enabled" | "debug", boolean>> & Record<string, boolean>
+    Partial<Record<"enabled" | "debug", boolean>> & Record<string, boolean | undefined>
   >();
 
   // With union value type
   type StringOrNumber = string | number;
   expectTypeOf<QueryParamsHint<"value", StringOrNumber>>().toEqualTypeOf<
-    Partial<Record<"value", StringOrNumber>> & Record<string, StringOrNumber>
+    Partial<Record<"value", StringOrNumber>> & Record<string, StringOrNumber | undefined>
   >();
 
   // With custom object type
   type CustomType = { raw: string; parsed: boolean };
   expectTypeOf<QueryParamsHint<"data", CustomType>>().toEqualTypeOf<
-    Partial<Record<"data", CustomType>> & Record<string, CustomType>
+    Partial<Record<"data", CustomType>> & Record<string, CustomType | undefined>
   >();
 });
 

package/src/api/internal/path.ts

@@ -124,7 +124,7 @@ export type HasPathParams<T extends string> = ExtractPathParamNames<T> extends n
 export type QueryParamsHint<TQueryParameters extends string, ValueType = string> = Partial<
   Record<TQueryParameters, ValueType>
 > &
-  Record<string, ValueType>;
+  Record<string, ValueType | undefined>;
 
 // Runtime utilities
 

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-types.test.ts

@@ -417,7 +417,7 @@ describe("FragnoClientMutatorData", () => {
       (args?: {
         body?: undefined;
         path?: Record<"id", string> | undefined;
-        query?: Record<string, string>;
+        query?: Record<string, string | undefined>;
       }) => Promise<undefined>
     >();
   });
@@ -437,7 +437,7 @@ describe("FragnoClientMutatorData", () => {
       (args?: {
         body?: undefined;
         path?: Record<"id", string> | undefined;
-        query?: Record<string, string>;
+        query?: Record<string, string | undefined>;
       }) => Promise<{
         id: number;
         name: string;
@@ -465,7 +465,7 @@ describe("FragnoClientMutatorData", () => {
             }
           | undefined;
         path?: Record<"id", string> | undefined;
-        query?: Record<string, string>;
+        query?: Record<string, string | undefined>;
       }) => Promise<undefined>
     >();
   });
@@ -486,7 +486,7 @@ describe("FragnoClientMutatorData", () => {
       (args?: {
         body?: undefined;
         path?: Record<"id", string> | undefined;
-        query?: Record<"id" | "name", string>;
+        query?: Record<"id" | "name", string | undefined>;
       }) => Promise<undefined>
     >();
   });

package/src/client/client.test.ts

@@ -445,6 +445,83 @@ describe("hook parameter reactivity", () => {
     }
   });
 
+  test("should react to optional query parameters", async () => {
+    const testFragment = defineFragment("test-fragment");
+    const testRoutes = [
+      defineRoute({
+        method: "GET",
+        path: "/users",
+        queryParameters: ["thing"],
+        outputSchema: z.array(z.object({ id: z.number(), name: z.string(), suffix: z.string() })),
+        handler: async (_ctx, { json }) => json([{ id: 1, name: "John", suffix: "default" }]),
+      }),
+    ] as const;
+
+    vi.mocked(global.fetch).mockImplementation(async (input) => {
+      assert(typeof input === "string");
+
+      const url = new URL(input);
+      const thing = url.searchParams.get("thing");
+
+      const suffix = thing ? `with-${thing}` : "without-thing";
+
+      return {
+        headers: new Headers(),
+        ok: true,
+        json: async () => [{ id: 1, name: "John", suffix }],
+      } as Response;
+    });
+
+    const cb = createClientBuilder(testFragment, clientConfig, testRoutes);
+    const useUsers = cb.createHook("/users");
+
+    // This atom with string | undefined type should be accepted by the query parameter
+    const thingAtom = atom<string | undefined>("initial");
+
+    const store = useUsers.store({ query: { thing: thingAtom } });
+
+    const itt = createAsyncIteratorFromCallback(store.listen);
+
+    {
+      const { value } = await itt.next();
+      expect(value).toEqual({
+        loading: true,
+        promise: expect.any(Promise),
+        data: undefined,
+        error: undefined,
+      });
+    }
+
+    {
+      const { value } = await itt.next();
+      expect(value).toEqual({
+        loading: false,
+        data: [{ id: 1, name: "John", suffix: "with-initial" }],
+      });
+    }
+
+    // Change thing to another value
+    thingAtom.set(undefined);
+
+    {
+      const { value } = await itt.next();
+      expect(value).toEqual({
+        loading: true,
+        promise: expect.any(Promise),
+        data: undefined,
+        error: undefined,
+      });
+    }
+
+    {
+      const { value } = await itt.next();
+      expect(value).toEqual({
+        loading: false,
+        data: [{ id: 1, name: "John", suffix: "without-thing" }],
+      });
+    }
+  });
+
   test("should react to combined path and query parameters", async () => {
     const testFragment = defineFragment("test-fragment");
     const testRoutes = [
@@ -1688,3 +1765,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");
+  });
+});