@fragno-dev/core 0.1.5 → 0.1.7

package/src/client/client.ts

@@ -1,6 +1,6 @@
 import { nanoquery, type FetcherStore, type MutatorStore } from "@nanostores/query";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { task, type ReadableAtom, type Store } from "nanostores";
+import { computed, task, type ReadableAtom, type Store } from "nanostores";
 import type { FragnoRouteConfig, HTTPMethod, NonGetHTTPMethod } from "../api/api";
 import {
   buildPath,
@@ -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
@@ -250,11 +252,11 @@ export type FragnoClientHookData<
   >;
   query(args?: {
     path?: MaybeExtractPathParamsOrWiden<TPath, string>;
-    query?: Record<TQueryParameters, string>;
+    query?: Record<TQueryParameters, string | undefined>;
   }): Promise<StandardSchemaV1.InferOutput<TOutputSchema>>;
   store(args?: {
     path?: MaybeExtractPathParamsOrWiden<TPath, string | ReadableAtom<string>>;
-    query?: Record<TQueryParameters, string | ReadableAtom<string>>;
+    query?: Record<TQueryParameters, string | undefined | ReadableAtom<string | undefined>>;
   }): FetcherStore<StandardSchemaV1.InferOutput<TOutputSchema>, FragnoClientError<TErrorCode>>;
   [GET_HOOK_SYMBOL]: true;
 } & {
@@ -285,14 +287,14 @@ export type FragnoClientMutatorData<
   mutateQuery(args?: {
     body?: InferOr<TInputSchema, undefined>;
     path?: MaybeExtractPathParamsOrWiden<TPath, string>;
-    query?: Record<TQueryParameters, string>;
+    query?: Record<TQueryParameters, string | undefined>;
   }): Promise<InferOr<TOutputSchema, undefined>>;
 
   mutatorStore: MutatorStore<
     {
       body?: InferOr<TInputSchema, undefined>;
       path?: MaybeExtractPathParamsOrWiden<TPath, string | ReadableAtom<string>>;
-      query?: Record<TQueryParameters, string | ReadableAtom<string>>;
+      query?: Record<TQueryParameters, string | undefined | ReadableAtom<string | undefined>>;
     },
     InferOr<TOutputSchema, undefined>,
     FragnoClientError<TErrorCode>
@@ -311,7 +313,7 @@ export function buildUrl<TPath extends string>(
   },
   params: {
     pathParams?: Record<string, string | ReadableAtom<string>>;
-    queryParams?: Record<string, string | ReadableAtom<string>>;
+    queryParams?: Record<string, string | undefined | ReadableAtom<string | undefined>>;
   },
 ): string {
   const { baseUrl = "", mountRoute, path } = config;
@@ -320,7 +322,12 @@ export function buildUrl<TPath extends string>(
   const normalizedPathParams = unwrapObject(pathParams) as ExtractPathParams<TPath, string>;
   const normalizedQueryParams = unwrapObject(queryParams) ?? {};
 
-  const searchParams = new URLSearchParams(normalizedQueryParams);
+  // Filter out undefined values to prevent URLSearchParams from converting them to string "undefined"
+  const filteredQueryParams = Object.fromEntries(
+    Object.entries(normalizedQueryParams).filter(([_, value]) => value !== undefined),
+  ) as Record<string, string>;
+
+  const searchParams = new URLSearchParams(filteredQueryParams);
   const builtPath = buildPath(path, normalizedPathParams ?? {});
   const search = searchParams.toString() ? `?${searchParams.toString()}` : "";
   return `${baseUrl}${mountRoute}${builtPath}${search}`;
@@ -331,6 +338,7 @@ export function buildUrl<TPath extends string>(
  *
  * The returned array is always: path, pathParams (In order they appear in the path), queryParams (In alphabetical order)
  * Missing pathParams are replaced with "<missing>".
+ * Atoms with undefined values are wrapped in computed atoms that map undefined to "" to avoid nanoquery treating the key as incomplete.
  * @param path
  * @param params
  * @returns
@@ -340,7 +348,7 @@ export function getCacheKey<TMethod extends HTTPMethod, TPath extends string>(
   path: TPath,
   params?: {
     pathParams?: Record<string, string | ReadableAtom<string>>;
-    queryParams?: Record<string, string | ReadableAtom<string>>;
+    queryParams?: Record<string, string | undefined | ReadableAtom<string | undefined>>;
   },
 ): (string | ReadableAtom<string>)[] {
   if (!params) {
@@ -355,7 +363,15 @@ export function getCacheKey<TMethod extends HTTPMethod, TPath extends string>(
   const queryParamValues = queryParams
     ? Object.keys(queryParams)
         .sort()
-        .map((key) => queryParams[key])
+        .map((key) => {
+          const value = queryParams[key];
+          // If it's an atom, wrap it to convert undefined to ""
+          if (value && typeof value === "object" && "get" in value) {
+            return computed(value as ReadableAtom<string | undefined>, (v) => v ?? "");
+          }
+          // Plain string value (or undefined)
+          return value ?? "";
+        })
     : [];
 
   return [method, path, ...pathParamValues, ...queryParamValues];
@@ -487,6 +503,7 @@ export class ClientBuilder<
 > {
   #publicConfig: FragnoPublicClientConfig;
   #fragmentConfig: TFragmentConfig;
+  #fetcherConfig?: FetcherConfig;
 
   #cache = new Map<string, CacheLine>();
 
@@ -497,6 +514,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 +532,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,17 +677,24 @@ 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>>;
-      queryParams?: Record<string, string | ReadableAtom<string>>;
+      queryParams?: Record<string, string | undefined | ReadableAtom<string | undefined>>;
     }): Promise<Response> {
       const { pathParams, queryParams } = params ?? {};
 
       const normalizedPathParams = unwrapObject(pathParams) as ExtractPathParams<TPath, string>;
       const normalizedQueryParams = unwrapObject(queryParams) ?? {};
 
-      const searchParams = new URLSearchParams(normalizedQueryParams);
+      // Filter out undefined values to prevent URLSearchParams from converting them to string "undefined"
+      const filteredQueryParams = Object.fromEntries(
+        Object.entries(normalizedQueryParams).filter(([_, value]) => value !== undefined),
+      ) as Record<string, string>;
+
+      const searchParams = new URLSearchParams(filteredQueryParams);
 
       const result = await route.handler(
         RequestInputContext.fromSSRContext({
@@ -638,7 +711,7 @@ export class ClientBuilder<
 
     async function executeQuery(params?: {
       pathParams?: Record<string, string | ReadableAtom<string>>;
-      queryParams?: Record<string, string | ReadableAtom<string>>;
+      queryParams?: Record<string, string | undefined | ReadableAtom<string | undefined>>;
     }): Promise<Response> {
       const { pathParams, queryParams } = params ?? {};
 
@@ -650,7 +723,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 +868,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 +903,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 +1085,7 @@ export function createClientBuilder<
   },
   publicConfig: FragnoPublicClientConfig,
   routesOrFactories: TRoutesOrFactories,
+  authorFetcherConfig?: FetcherConfig,
 ): ClientBuilder<
   FlattenRouteFactories<TRoutesOrFactories>,
   FragnoFragmentSharedConfig<FlattenRouteFactories<TRoutesOrFactories>>
@@ -1030,12 +1108,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;
+}