@fragno-dev/core 0.2.0 → 0.2.2

package/src/client/client.ts

@@ -1,6 +1,8 @@
+import { computed, task, type ReadableAtom, type Store } from "nanostores";
+
 import { nanoquery, type FetcherStore, type MutatorStore } from "@nanostores/query";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { computed, task, type ReadableAtom, type Store } from "nanostores";
+
 import type {
   FragnoRouteConfig,
   HTTPMethod,
@@ -8,6 +10,7 @@ import type {
   RequestThisContext,
   RouteContentType,
 } from "../api/api";
+import type { FragmentDefinition } from "../api/fragment-definition-builder";
 import {
   buildPath,
   extractPathParams,
@@ -18,29 +21,28 @@ import {
 import { getMountRoute } from "../api/internal/route";
 import { RequestInputContext } from "../api/request-input-context";
 import { RequestOutputContext } from "../api/request-output-context";
+import {
+  type AnyFragnoRouteConfig,
+  type AnyRouteOrFactory,
+  type FlattenRouteFactories,
+  resolveRouteFactories,
+} from "../api/route";
 import type {
   FetcherConfig,
   FragnoFragmentSharedConfig,
   FragnoPublicClientConfig,
   FragnoPublicConfig,
 } from "../api/shared-types";
-import { FragnoClientApiError, FragnoClientError, FragnoClientFetchError } from "./client-error";
-import type { InferOr } from "../util/types-util";
 import { parseContentType } from "../util/content-type";
+import { unwrapObject } from "../util/nanostores";
+import { addStore, getInitialData, SSR_ENABLED } from "../util/ssr";
+import type { InferOr } from "../util/types-util";
+import { FragnoClientApiError, FragnoClientError, FragnoClientFetchError } from "./client-error";
+import { mergeFetcherConfigs } from "./internal/fetcher-merge";
 import {
   handleNdjsonStreamingFirstItem,
   type NdjsonStreamingStore,
 } from "./internal/ndjson-streaming";
-import { addStore, getInitialData, SSR_ENABLED } from "../util/ssr";
-import { unwrapObject } from "../util/nanostores";
-import type { FragmentDefinition } from "../api/fragment-definition-builder";
-import type { AnyFragnoInstantiatedFragment } from "../api/fragment-instantiator";
-import {
-  type AnyRouteOrFactory,
-  type FlattenRouteFactories,
-  resolveRouteFactories,
-} from "../api/route";
-import { mergeFetcherConfigs } from "./internal/fetcher-merge";
 
 /**
  * Symbols used to identify hook types
@@ -153,6 +155,31 @@ function prepareRequestBody(
   };
 }
 
+async function schemaAllowsUndefined(schema: StandardSchemaV1): Promise<boolean> {
+  try {
+    const result = await schema["~standard"].validate(undefined);
+    return !result.issues;
+  } catch {
+    return false;
+  }
+}
+
+async function assertBodyProvided(
+  body: unknown,
+  inputSchema: StandardSchemaV1 | undefined,
+  errorMessage: string,
+): Promise<void> {
+  if (typeof body !== "undefined" || inputSchema === undefined) {
+    return;
+  }
+
+  if (await schemaAllowsUndefined(inputSchema)) {
+    return;
+  }
+
+  throw new Error(errorMessage);
+}
+
 /**
  * Merge request headers from multiple sources.
  * Returns undefined if there are no headers to merge.
@@ -191,58 +218,128 @@ function mergeRequestHeaders(
 }
 
 /**
- * Extract only GET routes from a library config's routes array
  * @internal
  */
-export type ExtractGetRoutes<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
-> = {
+type FilterRouteByMethod<TRoute, TExpectedMethod extends HTTPMethod> =
+  TRoute extends FragnoRouteConfig<
+    infer TMethod,
+    infer TPath,
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
+  >
+    ? [Extract<TMethod, TExpectedMethod>] extends [never]
+      ? [Extract<TExpectedMethod, TMethod>] extends [never]
+        ? never
+        : FragnoRouteConfig<
+            TMethod,
+            TPath,
+            TInputSchema,
+            TOutputSchema,
+            TErrorCode,
+            TQueryParameters,
+            TThisContext
+          >
+      : FragnoRouteConfig<
+          TMethod,
+          TPath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          TThisContext
+        >
+    : never;
+
+/**
+ * @internal
+ */
+type FilterRouteByPath<TRoute, TPath extends string> =
+  TRoute extends FragnoRouteConfig<
+    infer TMethod,
+    infer TRoutePath,
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
+  >
+    ? [Extract<TRoutePath, TPath>] extends [never]
+      ? [Extract<TPath, TRoutePath>] extends [never]
+        ? never
+        : FragnoRouteConfig<
+            TMethod,
+            TRoutePath,
+            TInputSchema,
+            TOutputSchema,
+            TErrorCode,
+            TQueryParameters,
+            TThisContext
+          >
+      : FragnoRouteConfig<
+          TMethod,
+          TRoutePath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          TThisContext
+        >
+    : never;
+
+/**
+ * @internal
+ */
+type ExtractGetRoutesExact<T extends readonly AnyFragnoRouteConfig[]> = {
   [K in keyof T]: T[K] extends FragnoRouteConfig<
-    infer Method,
-    infer Path,
-    infer Input,
-    infer Output,
-    infer ErrorCode,
-    infer QueryParams
+    infer TMethod,
+    infer TPath,
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
   >
-    ? Method extends "GET"
-      ? FragnoRouteConfig<Method, Path, Input, Output, ErrorCode, QueryParams>
+    ? TMethod extends "GET"
+      ? FragnoRouteConfig<
+          TMethod,
+          TPath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          TThisContext
+        >
       : never
     : never;
 }[number][];
 
 /**
- * Extract the path from a route configuration for a given method
+ * Extract only GET routes from a library config's routes array
  * @internal
  */
-export type ExtractRoutePath<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
+export type ExtractGetRoutes<T extends readonly AnyFragnoRouteConfig[]> = ExtractGetRoutesExact<T>;
+
+/**
+ * @internal
+ */
+type ExtractRoutePathExact<
+  T extends readonly AnyFragnoRouteConfig[],
   TExpectedMethod extends HTTPMethod = HTTPMethod,
 > = {
   [K in keyof T]: T[K] extends FragnoRouteConfig<
-    infer Method,
-    infer Path,
+    infer TMethod,
+    infer TPath,
     StandardSchemaV1 | undefined,
     StandardSchemaV1 | undefined,
     string,
-    string
+    string,
+    RequestThisContext
   >
-    ? Method extends TExpectedMethod
-      ? Path
+    ? TMethod extends TExpectedMethod
+      ? TPath
       : never
     : never;
 }[number];
@@ -250,103 +347,154 @@ export type ExtractRoutePath<
 /**
  * @internal
  */
-export type ExtractGetRoutePaths<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
+type ExtractRoutePathLoose<
+  T extends readonly AnyFragnoRouteConfig[],
+  TExpectedMethod extends HTTPMethod = HTTPMethod,
+> = {
+  [K in keyof T]: FilterRouteByMethod<T[K], TExpectedMethod> extends FragnoRouteConfig<
+    infer _TMethod,
+    infer TPath,
     StandardSchemaV1 | undefined,
     StandardSchemaV1 | undefined,
     string,
-    string
-  >[],
-> = ExtractRoutePath<T, "GET">;
+    string,
+    RequestThisContext
+  >
+    ? TPath
+    : never;
+}[number];
 
 /**
  * @internal
  */
-export type ExtractNonGetRoutePaths<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
-> = ExtractRoutePath<T, NonGetHTTPMethod>;
+type HasWidenedRouteShape<T extends readonly AnyFragnoRouteConfig[]> =
+  T[number] extends infer TRoute
+    ? TRoute extends FragnoRouteConfig<
+        infer TMethod,
+        infer TPath,
+        StandardSchemaV1 | undefined,
+        StandardSchemaV1 | undefined,
+        string,
+        string,
+        RequestThisContext
+      >
+      ? string extends TPath
+        ? true
+        : HTTPMethod extends TMethod
+          ? true
+          : false
+      : false
+    : false;
 
 /**
- * Extract the route configuration type(s) for a given path from a routes array.
- * Optionally narrow by HTTP method via the third type parameter.
- *
- * Defaults to extracting all methods for the matching path, producing a union
- * if multiple methods exist for the same path.
+ * Extract the path from a route configuration for a given method
  * @internal
  */
-export type ExtractRouteByPath<
-  TRoutes extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
+export type ExtractRoutePath<
+  T extends readonly AnyFragnoRouteConfig[],
+  TExpectedMethod extends HTTPMethod = HTTPMethod,
+> = [ExtractRoutePathExact<T, TExpectedMethod>] extends [never]
+  ? HasWidenedRouteShape<T> extends true
+    ? ExtractRoutePathLoose<T, TExpectedMethod> & string
+    : never
+  : ExtractRoutePathExact<T, TExpectedMethod>;
+
+/**
+ * @internal
+ */
+export type ExtractGetRoutePaths<T extends readonly AnyFragnoRouteConfig[]> = ExtractRoutePath<
+  T,
+  "GET"
+>;
+
+/**
+ * @internal
+ */
+export type ExtractNonGetRoutePaths<T extends readonly AnyFragnoRouteConfig[]> = ExtractRoutePath<
+  T,
+  NonGetHTTPMethod
+>;
+
+/**
+ * @internal
+ */
+type ExtractRouteByPathExact<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
   TPath extends string,
   TMethod extends HTTPMethod = HTTPMethod,
 > = {
   [K in keyof TRoutes]: TRoutes[K] extends FragnoRouteConfig<
-    infer M,
+    infer TRouteMethod,
     TPath,
-    infer Input,
-    infer Output,
-    infer ErrorCode,
-    infer QueryParams
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
   >
-    ? M extends TMethod
-      ? FragnoRouteConfig<M, TPath, Input, Output, ErrorCode, QueryParams>
+    ? TRouteMethod extends TMethod
+      ? FragnoRouteConfig<
+          TRouteMethod,
+          TPath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          TThisContext
+        >
       : never
     : never;
 }[number];
 
+/**
+ * @internal
+ */
+type ExtractRouteByPathLoose<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TPath extends string,
+  TMethod extends HTTPMethod = HTTPMethod,
+> = {
+  [K in keyof TRoutes]: FilterRouteByPath<FilterRouteByMethod<TRoutes[K], TMethod>, TPath>;
+}[number];
+
+/**
+ * Extract the route configuration type(s) for a given path from a routes array.
+ * Optionally narrow by HTTP method via the third type parameter.
+ *
+ * Defaults to extracting all methods for the matching path, producing a union
+ * if multiple methods exist for the same path.
+ * @internal
+ */
+export type ExtractRouteByPath<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TPath extends string,
+  TMethod extends HTTPMethod = HTTPMethod,
+> = [ExtractRouteByPathExact<TRoutes, TPath, TMethod>] extends [never]
+  ? HasWidenedRouteShape<TRoutes> extends true
+    ? ExtractRouteByPathLoose<TRoutes, TPath, TMethod>
+    : never
+  : ExtractRouteByPathExact<TRoutes, TPath, TMethod>;
+
 /**
  * Extract the output schema type for a specific route path from a routes array
  * @internal
  */
 export type ExtractOutputSchemaForPath<
-  TRoutes extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined
-  >[],
+  TRoutes extends readonly AnyFragnoRouteConfig[],
   TPath extends string,
-> = {
-  [K in keyof TRoutes]: TRoutes[K] extends FragnoRouteConfig<
-    infer Method,
-    TPath,
-    StandardSchemaV1 | undefined,
-    infer Output
-  >
-    ? Method extends "GET"
-      ? Output
-      : never
+> =
+  ExtractRouteByPath<TRoutes, TPath, "GET"> extends {
+    outputSchema?: infer TOutputSchema;
+  }
+    ? TOutputSchema
     : never;
-}[number];
 
 /**
  * Check if a path exists as a GET route in the routes array
  * @internal
  */
 export type IsValidGetRoutePath<
-  TRoutes extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
+  TRoutes extends readonly AnyFragnoRouteConfig[],
   TPath extends string,
 > = TPath extends ExtractGetRoutePaths<TRoutes> ? true : false;
 
@@ -355,14 +503,7 @@ export type IsValidGetRoutePath<
  * @internal
  */
 export type ValidateGetRoutePath<
-  TRoutes extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
+  TRoutes extends readonly AnyFragnoRouteConfig[],
   TPath extends string,
 > =
   TPath extends ExtractGetRoutePaths<TRoutes>
@@ -373,16 +514,8 @@ export type ValidateGetRoutePath<
  * Helper type to check if a routes array has any GET routes
  * @internal
  */
-export type HasGetRoutes<
-  T extends readonly FragnoRouteConfig<
-    HTTPMethod,
-    string,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined,
-    string,
-    string
-  >[],
-> = ExtractGetRoutePaths<T> extends never ? false : true;
+export type HasGetRoutes<T extends readonly AnyFragnoRouteConfig[]> =
+  ExtractGetRoutePaths<T> extends never ? false : true;
 
 /**
  * @internal
@@ -398,11 +531,20 @@ export type ObjectContainingStoreField<T extends object> = T extends Store
 /**
  * @internal
  */
-export type FragnoStoreData<T extends object> = {
+export type FragnoStoreObjectData<T extends object> = {
   obj: T;
   [STORE_SYMBOL]: true;
 };
 
+export type FragnoStoreFactoryData<T extends object, TArgs extends unknown[] = []> = {
+  factory: (...args: TArgs) => T;
+  [STORE_SYMBOL]: true;
+};
+
+export type FragnoStoreData<T extends object, TArgs extends unknown[] = []> =
+  | FragnoStoreObjectData<T>
+  | FragnoStoreFactoryData<T, TArgs>;
+
 export type FragnoClientHookData<
   TMethod extends HTTPMethod,
   TPath extends string,
@@ -627,7 +769,9 @@ export function isMutatorHook<
 /**
  * @internal
  */
-export function isStore<TStore extends Store>(obj: unknown): obj is FragnoStoreData<TStore> {
+export function isStore<TStore extends object, TArgs extends unknown[] = []>(
+  obj: unknown,
+): obj is FragnoStoreData<TStore, TArgs> {
   return (
     typeof obj === "object" && obj !== null && STORE_SYMBOL in obj && obj[STORE_SYMBOL] === true
   );
@@ -712,8 +856,18 @@ export class ClientBuilder<
     return Object.fromEntries(this.#cache.entries());
   }
 
-  createStore<const T extends object>(obj: T): FragnoStoreData<T> {
-    return { obj: obj, [STORE_SYMBOL]: true };
+  createStore<const TArgs extends unknown[], const T extends object>(
+    factory: (...args: TArgs) => T,
+  ): FragnoStoreFactoryData<T, TArgs>;
+  createStore<const T extends object>(obj: T): FragnoStoreObjectData<T>;
+  createStore<const TArgs extends unknown[], const T extends object>(
+    input: T | ((...args: TArgs) => T),
+  ): FragnoStoreData<T, TArgs> {
+    if (typeof input === "function") {
+      return { factory: input as (...args: TArgs) => T, [STORE_SYMBOL]: true };
+    }
+
+    return { obj: input, [STORE_SYMBOL]: true };
   }
 
   /**
@@ -757,7 +911,7 @@ export class ClientBuilder<
     if (this.#fetcherConfig?.type === "function") {
       return this.#fetcherConfig.fetcher;
     }
-    return fetch;
+    return globalThis.fetch.bind(globalThis);
   }
 
   #getFetcherOptions(): RequestInit | undefined {
@@ -1150,9 +1304,7 @@ export class ClientBuilder<
           query?: Record<string, string>;
         };
 
-        if (typeof body === "undefined" && route.inputSchema !== undefined) {
-          throw new Error("Body is required.");
-        }
+        await assertBodyProvided(body, route.inputSchema, "Body is required.");
 
         const response = await executeMutateQuery({ body, path, query });
 
@@ -1221,9 +1373,7 @@ export class ClientBuilder<
         query?: Record<string, string>;
       };
 
-      if (typeof body === "undefined" && route.inputSchema !== undefined) {
-        throw new Error("Body is required for mutateQuery");
-      }
+      await assertBodyProvided(body, route.inputSchema, "Body is required for mutateQuery");
 
       const response = await executeMutateQuery({ body, path, query });
 
@@ -1300,7 +1450,7 @@ export function createClientBuilder<
   THandlerThisContext extends RequestThisContext,
   TRequestStorage,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},
+  TInternalRoutes extends readonly AnyRouteOrFactory[] = readonly [],
 >(
   definition: FragmentDefinition<
     TConfig,
@@ -1313,7 +1463,7 @@ export function createClientBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >,
   publicConfig: FragnoPublicClientConfig,
   routesOrFactories: TRoutesOrFactories,

package/src/client/internal/ndjson-streaming.test.ts

@@ -1,10 +1,13 @@
 import { describe, test, expect, vi } from "vitest";
-import { handleNdjsonStreamingFirstItem, type NdjsonStreamingStore } from "./ndjson-streaming";
-import { FragnoClientError, FragnoClientFetchAbortError } from "../client-error";
-import { nanoquery } from "@nanostores/query";
+
 import { z } from "zod";
+
+import { nanoquery } from "@nanostores/query";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import { createAsyncIteratorFromCallback } from "../../util/async";
+import { FragnoClientError, FragnoClientFetchAbortError } from "../client-error";
+import { handleNdjsonStreamingFirstItem, type NdjsonStreamingStore } from "./ndjson-streaming";
 
 describe("handleNdjsonStreaming", () => {
   test("should return first item and continue streaming updates", async () => {

package/src/client/internal/ndjson-streaming.ts

@@ -1,4 +1,5 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import {
   FragnoClientError,
   FragnoClientFetchError,