@fragno-dev/core 0.1.11 → 0.2.2

package/src/api/route-caller.ts

@@ -0,0 +1,167 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+import type { ExtractRouteByPath, ExtractRoutePath } from "../client/client";
+import type { InferOrUnknown } from "../util/types-util";
+import type { HTTPMethod } from "./api";
+import type { FragnoResponse } from "./fragno-response";
+import { parseFragnoResponse } from "./fragno-response";
+import { buildPath, type ExtractPathParams } from "./internal/path";
+import type { AnyFragnoRouteConfig } from "./route";
+import type { RouteHandlerInputOptions } from "./route-handler-input-options";
+
+export type RouteCallerConfig = {
+  baseUrl: string | URL;
+  mountRoute?: string;
+  baseHeaders?: HeadersInit;
+  fetch: (request: Request) => Promise<Response>;
+  redirect?: RequestRedirect;
+};
+
+type ArrayBufferViewOfArrayBuffer = ArrayBufferView & { buffer: ArrayBuffer };
+
+type FragmentLike = {
+  routes?: readonly AnyFragnoRouteConfig[];
+  callRoute?: (...args: never[]) => Promise<unknown>;
+};
+
+type RouteCallerPath<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TMethod extends HTTPMethod,
+> = [ExtractRoutePath<TRoutes, TMethod>] extends [never]
+  ? string
+  : ExtractRoutePath<TRoutes, TMethod>;
+
+type RouteCallerMatch<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TMethod extends HTTPMethod,
+  TPath extends string,
+> = [ExtractRouteByPath<TRoutes, TPath, TMethod>] extends [never]
+  ? AnyFragnoRouteConfig
+  : ExtractRouteByPath<TRoutes, TPath, TMethod>;
+
+export type RouteCallerForFragment<TFragment extends FragmentLike> = TFragment extends {
+  routes: infer TRoutes extends readonly AnyFragnoRouteConfig[];
+}
+  ? <TMethod extends HTTPMethod, TPath extends RouteCallerPath<TRoutes, TMethod>>(
+      method: TMethod,
+      path: TPath,
+      inputOptions?: RouteHandlerInputOptions<
+        TPath,
+        RouteCallerMatch<TRoutes, TMethod, TPath>["inputSchema"]
+      >,
+    ) => Promise<
+      FragnoResponse<
+        InferOrUnknown<NonNullable<RouteCallerMatch<TRoutes, TMethod, TPath>["outputSchema"]>>
+      >
+    >
+  : TFragment extends { callRoute: (...args: never[]) => Promise<unknown> }
+    ? TFragment["callRoute"]
+    : never;
+
+function isArrayBufferView(value: unknown): value is ArrayBufferViewOfArrayBuffer {
+  return ArrayBuffer.isView(value) && value.buffer instanceof ArrayBuffer;
+}
+
+function buildMountedPath(mountRoute: string, pathname: string): string {
+  const normalizedMount =
+    mountRoute === "/" ? "" : mountRoute.endsWith("/") ? mountRoute.slice(0, -1) : mountRoute;
+  const pathPart = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  if (!normalizedMount) {
+    return pathPart;
+  }
+  const mountPart = normalizedMount.startsWith("/") ? normalizedMount : `/${normalizedMount}`;
+  return `${mountPart}${pathPart}`;
+}
+
+export function createRouteCaller<TFragment extends FragmentLike>(
+  config: RouteCallerConfig,
+): RouteCallerForFragment<TFragment> {
+  const { baseUrl, fetch } = config;
+  const mountRoute = config.mountRoute ?? "";
+  const baseHeaders = config.baseHeaders ? new Headers(config.baseHeaders) : undefined;
+  const redirect = config.redirect ?? "manual";
+
+  const callRoute = async <TPath extends string>(
+    method: HTTPMethod,
+    path: TPath,
+    inputOptions?: RouteHandlerInputOptions<TPath, StandardSchemaV1 | undefined>,
+  ): Promise<FragnoResponse<unknown>> => {
+    const headers = baseHeaders ? new Headers(baseHeaders) : new Headers();
+    const explicitHeaders = inputOptions?.headers
+      ? inputOptions.headers instanceof Headers
+        ? inputOptions.headers
+        : new Headers(inputOptions.headers)
+      : null;
+
+    if (explicitHeaders) {
+      for (const [key, value] of explicitHeaders.entries()) {
+        headers.set(key, value);
+      }
+    }
+
+    const hasExplicitContentType = explicitHeaders?.has("content-type") ?? false;
+
+    const searchParams =
+      inputOptions?.query instanceof URLSearchParams
+        ? new URLSearchParams(inputOptions.query)
+        : new URLSearchParams();
+
+    if (inputOptions?.query && !(inputOptions.query instanceof URLSearchParams)) {
+      for (const [key, value] of Object.entries(inputOptions.query)) {
+        if (value !== undefined) {
+          searchParams.set(key, value);
+        }
+      }
+    }
+
+    const pathParams = (inputOptions?.pathParams ?? {}) as ExtractPathParams<TPath>;
+    const pathname = buildPath(path, pathParams);
+    const url = new URL(buildMountedPath(mountRoute, pathname), baseUrl);
+    url.search = searchParams.toString();
+
+    let body: BodyInit | undefined;
+    if (inputOptions && "body" in inputOptions) {
+      const rawBody = (inputOptions as { body?: unknown }).body;
+
+      if (rawBody instanceof FormData || rawBody instanceof Blob) {
+        body = rawBody;
+        if (!hasExplicitContentType) {
+          headers.delete("content-type");
+        }
+      } else if (rawBody instanceof ReadableStream) {
+        body = rawBody;
+        if (!hasExplicitContentType) {
+          headers.delete("content-type");
+        }
+      } else if (rawBody instanceof ArrayBuffer) {
+        body = rawBody;
+        if (!hasExplicitContentType) {
+          headers.delete("content-type");
+        }
+      } else if (isArrayBufferView(rawBody)) {
+        body = rawBody;
+        if (!hasExplicitContentType) {
+          headers.delete("content-type");
+        }
+      } else if (rawBody !== undefined) {
+        body = JSON.stringify(rawBody);
+        if (!hasExplicitContentType) {
+          headers.set("content-type", "application/json");
+        }
+      }
+    }
+
+    const response = await fetch(
+      new Request(url, {
+        method,
+        headers,
+        body,
+        redirect,
+      }),
+    );
+
+    return parseFragnoResponse(response);
+  };
+
+  return callRoute as RouteCallerForFragment<TFragment>;
+}

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

@@ -1,6 +1,7 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { ExtractPathParams } from "./internal/path";
+
 import type { InferOr } from "../util/types-util";
+import type { ExtractPathParams } from "./internal/path";
 
 /**
  * Options for calling a route handler

package/src/api/route.test.ts

@@ -1,8 +1,10 @@
 import { test, expect, expectTypeOf, describe } from "vitest";
-import { defineRoute, defineRoutes } from "./route";
-import { defineFragment } from "./fragment-definition-builder";
+
 import { z } from "zod";
 
+import { defineFragment } from "./fragment-definition-builder";
+import { defineRoute, defineRoutes } from "./route";
+
 describe("defineRoute", () => {
   test("defineRoute no inputSchema", () => {
     const route = defineRoute({

package/src/api/route.ts

@@ -1,9 +1,10 @@
 // oxlint-disable no-explicit-any
 
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import type { FragnoRouteConfig, HTTPMethod, RequestThisContext } from "./api";
-import type { FragmentDefinition } from "./fragment-definition-builder";
 import type { BoundServices } from "./bind-services";
+import type { FragmentDefinition } from "./fragment-definition-builder";
 
 export type AnyFragnoRouteConfig = FragnoRouteConfig<HTTPMethod, string, any, any, any, any, any>;
 
@@ -182,18 +183,19 @@ export type AnyFragmentDefinition = FragmentDefinition<
   any,
   any,
   any,
+  any,
   any
 >;
 
 // Extract config from FragmentDefinition
 export type ExtractFragmentConfig<T> =
-  T extends FragmentDefinition<infer TConfig, any, any, any, any, any, any, any, any, any>
+  T extends FragmentDefinition<infer TConfig, any, any, any, any, any, any, any, any, any, any>
     ? TConfig
     : never;
 
 // Extract deps from FragmentDefinition
 export type ExtractFragmentDeps<T> =
-  T extends FragmentDefinition<any, any, infer TDeps, any, any, any, any, any, any, any>
+  T extends FragmentDefinition<any, any, infer TDeps, any, any, any, any, any, any, any, any>
     ? TDeps
     : never;
 
@@ -211,6 +213,7 @@ export type ExtractFragmentServices<T> =
     any,
     any,
     any,
+    any,
     any
   >
     ? BoundServices<TBaseServices & TServices>
@@ -228,6 +231,7 @@ export type ExtractFragmentServiceDeps<T> =
     any,
     any,
     any,
+    any,
     any
   >
     ? TServiceDependencies
@@ -245,6 +249,7 @@ export type ExtractFragmentServiceThisContext<T> =
     any,
     infer TServiceThisContext,
     any,
+    any,
     any
   >
     ? TServiceThisContext
@@ -262,6 +267,7 @@ export type ExtractFragmentHandlerThisContext<T> =
     any,
     any,
     infer THandlerThisContext,
+    any,
     any
   >
     ? THandlerThisContext

package/src/api/shared-types.ts

@@ -1,6 +1,7 @@
-import type { HTTPMethod } from "./api";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
+import type { HTTPMethod } from "./api";
+
 /**
  * Public configuration for Fragno fragments on the server side.
  */

package/src/client/client-builder.test.ts

@@ -1,9 +1,11 @@
 import { test, expect, expectTypeOf, describe } from "vitest";
+
 import { z } from "zod";
-import { createClientBuilder } from "./client";
-import { defineRoute } from "../api/route";
+
 import { defineFragment } from "../api/fragment-definition-builder";
+import { defineRoute } from "../api/route";
 import type { FragnoPublicClientConfig } from "../api/shared-types";
+import { createClientBuilder } from "./client";
 
 // Test route configurations
 const testFragment = defineFragment("test-fragment").build();

package/src/client/client-error.test.ts

@@ -1,7 +1,8 @@
 import { test, expect, describe } from "vitest";
-import { FragnoClientApiError, FragnoClientUnknownApiError } from "./client-error";
+
 import { FragnoApiError } from "../api/error";
 import { RequestOutputContext } from "../api/request-output-context";
+import { FragnoClientApiError, FragnoClientUnknownApiError } from "./client-error";
 
 describe("Error Conversion", () => {
   test("should convert API error to client error", async () => {

package/src/client/client-error.ts

@@ -112,7 +112,7 @@ export class FragnoClientApiError<
    * The type is `TErrorCode` (the set of known error codes for this route), but may also be a string
    * for forward compatibility with future error codes.
    */
-  get code(): TErrorCode | (string & {}) {
+  override get code(): TErrorCode | (string & {}) {
     return super.code as TErrorCode | (string & {});
   }
 

package/src/client/client-types.test.ts

@@ -1,18 +1,22 @@
 import { test, expectTypeOf, describe } from "vitest";
+
 import { z } from "zod";
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import { type FragnoRouteConfig, type HTTPMethod } from "../api/api";
-import { defineRoute } from "../api/route";
+import { type AnyFragnoRouteConfig, defineRoute } from "../api/route";
 import type {
   ExtractGetRoutes,
   ExtractGetRoutePaths,
   ExtractOutputSchemaForPath,
   ExtractRouteByPath,
+  ExtractRoutePath,
   IsValidGetRoutePath,
   ValidateGetRoutePath,
   HasGetRoutes,
   FragnoClientMutatorData,
 } from "./client";
-import type { StandardSchemaV1 } from "@standard-schema/spec";
 
 // Test route configurations for type testing
 const _testRoutes = [
@@ -150,12 +154,12 @@ test("ExtractOutputSchemaForPath type tests", () => {
 
   // Note: Routes without output schema have complex type inference, skipping direct test
 
-  // Should be never for non-existent path
+  // Non-existent paths currently widen to unknown, while routes without an output schema stay optional.
   type NonExistentSchema = ExtractOutputSchemaForPath<typeof _testRoutes, "/nonexistent">;
-  expectTypeOf<NonExistentSchema>().toEqualTypeOf<never>();
+  expectTypeOf<NonExistentSchema>().toEqualTypeOf<unknown>();
 
   type PathWithNoSchema = ExtractOutputSchemaForPath<typeof _testRoutes, "/home">;
-  expectTypeOf<PathWithNoSchema>().toEqualTypeOf<StandardSchemaV1<unknown, unknown> | undefined>();
+  expectTypeOf<PathWithNoSchema>().toEqualTypeOf<StandardSchemaV1<unknown, unknown>>();
 });
 
 test("IsValidGetRoutePath type tests", () => {
@@ -343,6 +347,16 @@ test("GET route with outputSchema", () => {
   expectTypeOf<ConstPaths>().toEqualTypeOf<"/test">();
 });
 
+test("route extraction falls back gracefully for widened route types", () => {
+  type BroadRoutes = readonly AnyFragnoRouteConfig[];
+
+  expectTypeOf<ExtractRoutePath<BroadRoutes, "POST">>().toEqualTypeOf<string>();
+  expectTypeOf<ExtractGetRoutePaths<BroadRoutes>>().toEqualTypeOf<string>();
+  expectTypeOf<
+    ExtractRouteByPath<BroadRoutes, "/users/:id", "POST">
+  >().toExtend<AnyFragnoRouteConfig>();
+});
+
 describe("ExtractRouteByPath", () => {
   const _fragmentConfig = {
     name: "test-fragment",

package/src/client/client.ssr.test.ts

@@ -7,12 +7,14 @@
  */
 
 import { describe, expect, test } from "vitest";
-import { type FragnoPublicClientConfig } from "./client";
-import { createClientBuilder } from "./client";
-import { defineRoute } from "../api/route";
-import { defineFragment } from "../api/fragment-definition-builder";
+
 import { z } from "zod";
+
+import { defineFragment } from "../api/fragment-definition-builder";
+import { defineRoute } from "../api/route";
 import { createAsyncIteratorFromCallback, waitForAsyncIterator } from "../util/async";
+import { type FragnoPublicClientConfig } from "./client";
+import { createClientBuilder } from "./client";
 
 describe("server side rendering", () => {
   const testFragmentDefinition = defineFragment("test-fragment").build();

package/src/client/client.svelte.test.ts

@@ -1,16 +1,19 @@
 import { test, expect, describe, vi, beforeEach, afterEach, assert } from "vitest";
-import { type FragnoPublicClientConfig } from "./client";
-import { createClientBuilder } from "./client";
+
+import { atom, computed } from "nanostores";
+import { writable, readable, get, derived } from "svelte/store";
+import { z } from "zod";
+
 import { render } from "@testing-library/svelte";
-import { defineRoute } from "../api/route";
+
 import { defineFragment } from "../api/fragment-definition-builder";
-import { z } from "zod";
-import { readableToAtom, useFragno } from "./client.svelte";
-import { writable, readable, get, derived } from "svelte/store";
+import { RequestOutputContext } from "../api/request-output-context";
+import { defineRoute } from "../api/route";
+import { type FragnoPublicClientConfig } from "./client";
+import { createClientBuilder } from "./client";
 import { FragnoClientUnknownApiError } from "./client-error";
+import { readableToAtom, useFragno } from "./client.svelte";
 import TestComponent from "./component.test.svelte";
-import { atom, computed } from "nanostores";
-import { RequestOutputContext } from "../api/request-output-context";
 
 function renderHook(
   clientObj: Record<string, unknown>,
@@ -766,7 +769,13 @@ describe("useFragno", () => {
       expect((get(hook.data) as TestData | undefined)?.id).toBe(456);
     });
 
-    expect(fetch).toHaveBeenCalledTimes(2);
+    const requestedIds = vi
+      .mocked(global.fetch)
+      .mock.calls.map(([input]) => String(input).match(/\/users\/([^/]+)/)?.[1])
+      .filter((id): id is string => id !== undefined);
+
+    expect(requestedIds).toContain("123");
+    expect(requestedIds).toContain("456");
   });
 });
 

package/src/client/client.svelte.ts

@@ -1,6 +1,12 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { atom, type ReadableAtom } from "nanostores";
+import { onDestroy } from "svelte";
+import { writable, type Readable, get } from "svelte/store";
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import type { NonGetHTTPMethod } from "../api/api";
+import type { MaybeExtractPathParamsOrWiden, QueryParamsHint } from "../api/internal/path";
+import type { InferOr } from "../util/types-util";
 import {
   isGetHook,
   isMutatorHook,
@@ -8,13 +14,10 @@ import {
   type FragnoClientHookData,
   type FragnoClientMutatorData,
   type FragnoStoreData,
+  type FragnoStoreFactoryData,
+  type FragnoStoreObjectData,
 } from "./client";
 import type { FragnoClientError } from "./client-error";
-import type { InferOr } from "../util/types-util";
-import type { MaybeExtractPathParamsOrWiden, QueryParamsHint } from "../api/internal/path";
-
-import { writable, type Readable, get } from "svelte/store";
-import { onDestroy } from "svelte";
 
 export type FragnoSvelteHook<
   _TMethod extends "GET",
@@ -223,10 +226,30 @@ function createSvelteMutator<
   };
 }
 
-export function createSvelteStore<T extends object>(hook: FragnoStoreData<T>): T {
-  // Since nanostores already implement Svelte's store contract,
-  // we can return the store object directly for use with $ syntax
-  return hook.obj;
+export type FragnoSvelteStore<T extends object, TArgs extends unknown[] = []> = TArgs extends []
+  ? T
+  : (...args: TArgs) => T;
+
+export function createSvelteStore<T extends object, TArgs extends unknown[]>(
+  hook: FragnoStoreData<T, TArgs>,
+): FragnoSvelteStore<T, TArgs> {
+  if ("obj" in hook) {
+    // Since nanostores already implement Svelte's store contract,
+    // we can return the store object directly for use with $ syntax
+    return hook.obj as FragnoSvelteStore<T, TArgs>;
+  }
+
+  return ((...args: TArgs) => {
+    const value = hook.factory(...args);
+    const disposer = value[Symbol.dispose as keyof typeof value];
+    if (typeof disposer === "function") {
+      onDestroy(() => {
+        disposer.call(value);
+      });
+    }
+
+    return value;
+  }) as FragnoSvelteStore<T, TArgs>;
 }
 
 export function useFragno<T extends Record<string, unknown>>(
@@ -249,9 +272,11 @@ export function useFragno<T extends Record<string, unknown>>(
           infer TQueryParameters
         >
       ? FragnoSvelteMutator<M, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>
-      : T[K] extends FragnoStoreData<infer TStoreObj>
-        ? TStoreObj
-        : T[K];
+      : T[K] extends FragnoStoreObjectData<infer TStoreObj>
+        ? FragnoSvelteStore<TStoreObj, []>
+        : T[K] extends FragnoStoreFactoryData<infer TStoreObj, infer TStoreArgs>
+          ? FragnoSvelteStore<TStoreObj, TStoreArgs>
+          : T[K];
 } {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const result = {} as any;