@fragno-dev/core 0.1.11 → 0.2.0

package/src/client/client.ts

@@ -6,6 +6,7 @@ import type {
   HTTPMethod,
   NonGetHTTPMethod,
   RequestThisContext,
+  RouteContentType,
 } from "../api/api";
 import {
   buildPath,
@@ -33,6 +34,7 @@ import {
 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,
@@ -47,6 +49,147 @@ const GET_HOOK_SYMBOL = Symbol("fragno-get-hook");
 const MUTATOR_HOOK_SYMBOL = Symbol("fragno-mutator-hook");
 const STORE_SYMBOL = Symbol("fragno-store");
 
+/**
+ * Check if a value contains files that should be sent as FormData.
+ * @internal
+ */
+function containsFiles(value: unknown): boolean {
+  if (value instanceof File || value instanceof Blob) {
+    return true;
+  }
+
+  if (value instanceof FormData) {
+    return true;
+  }
+
+  if (typeof value === "object" && value !== null) {
+    return Object.values(value).some(
+      (v) => v instanceof File || v instanceof Blob || v instanceof FormData,
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Convert an object containing files to FormData.
+ * Handles nested File/Blob values by appending them directly.
+ * Other values are JSON-stringified.
+ * @internal
+ */
+function toFormData(value: object): FormData {
+  const formData = new FormData();
+
+  for (const [key, val] of Object.entries(value)) {
+    if (val instanceof File) {
+      formData.append(key, val, val.name);
+    } else if (val instanceof Blob) {
+      formData.append(key, val);
+    } else if (val !== undefined && val !== null) {
+      // For non-file values, stringify if needed
+      formData.append(key, typeof val === "string" ? val : JSON.stringify(val));
+    }
+  }
+
+  return formData;
+}
+
+/**
+ * Prepare request body and headers for sending.
+ * Handles FormData (file uploads) vs JSON data.
+ * @internal
+ */
+function prepareRequestBody(
+  body: unknown,
+  contentType?: RouteContentType,
+): { body: BodyInit | undefined; headers?: HeadersInit } {
+  if (body === undefined) {
+    return { body: undefined };
+  }
+
+  if (contentType === "application/octet-stream") {
+    if (
+      body instanceof ReadableStream ||
+      body instanceof Blob ||
+      body instanceof File ||
+      body instanceof ArrayBuffer ||
+      body instanceof Uint8Array
+    ) {
+      return { body: body as BodyInit, headers: { "Content-Type": "application/octet-stream" } };
+    }
+
+    throw new Error(
+      "Octet-stream routes only accept Blob, File, ArrayBuffer, Uint8Array, or ReadableStream bodies.",
+    );
+  }
+
+  // If already FormData, send as-is (browser sets Content-Type with boundary)
+  if (body instanceof FormData) {
+    return { body };
+  }
+
+  // If body is directly a File or Blob, wrap it in FormData
+  if (body instanceof File) {
+    const formData = new FormData();
+    formData.append("file", body, body.name);
+    return { body: formData };
+  }
+
+  if (body instanceof Blob) {
+    const formData = new FormData();
+    formData.append("file", body);
+    return { body: formData };
+  }
+
+  // If object contains files, convert to FormData
+  if (typeof body === "object" && body !== null && containsFiles(body)) {
+    return { body: toFormData(body) };
+  }
+
+  // Otherwise, JSON-stringify
+  return {
+    body: JSON.stringify(body),
+    headers: { "Content-Type": "application/json" },
+  };
+}
+
+/**
+ * Merge request headers from multiple sources.
+ * Returns undefined if there are no headers to merge.
+ * @internal
+ */
+function mergeRequestHeaders(
+  ...headerSources: (HeadersInit | undefined)[]
+): Record<string, string> | undefined {
+  const result: Record<string, string> = {};
+  let hasHeaders = false;
+
+  for (const source of headerSources) {
+    if (!source) {
+      continue;
+    }
+
+    if (source instanceof Headers) {
+      for (const [key, value] of source.entries()) {
+        result[key] = value;
+        hasHeaders = true;
+      }
+    } else if (Array.isArray(source)) {
+      for (const [key, value] of source) {
+        result[key] = value;
+        hasHeaders = true;
+      }
+    } else {
+      for (const [key, value] of Object.entries(source)) {
+        result[key] = value;
+        hasHeaders = true;
+      }
+    }
+  }
+
+  return hasHeaders ? result : undefined;
+}
+
 /**
  * Extract only GET routes from a library config's routes array
  * @internal
@@ -585,7 +728,10 @@ export class ClientBuilder<
     },
   ): string {
     const baseUrl = this.#publicConfig.baseUrl ?? "";
-    const mountRoute = getMountRoute(this.#fragmentConfig);
+    const mountRoute = getMountRoute({
+      name: this.#fragmentConfig.name,
+      mountRoute: this.#publicConfig.mountRoute,
+    });
 
     return buildUrl(
       { baseUrl, mountRoute, path },
@@ -627,9 +773,11 @@ export class ClientBuilder<
   ): FragnoClientHookData<
     "GET",
     TPath,
-    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath>["outputSchema"]>,
-    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath>["errorCodes"]>[number],
-    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath>["queryParameters"]>[number]
+    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath, "GET">["outputSchema"]>,
+    NonNullable<ExtractRouteByPath<TFragmentConfig["routes"], TPath, "GET">["errorCodes"]>[number],
+    NonNullable<
+      ExtractRouteByPath<TFragmentConfig["routes"], TPath, "GET">["queryParameters"]
+    >[number]
   > {
     const route = this.#fragmentConfig.routes.find(
       (
@@ -717,7 +865,10 @@ export class ClientBuilder<
     }
 
     const baseUrl = this.#publicConfig.baseUrl ?? "";
-    const mountRoute = getMountRoute(this.#fragmentConfig);
+    const mountRoute = getMountRoute({
+      name: this.#fragmentConfig.name,
+      mountRoute: this.#publicConfig.mountRoute,
+    });
     const fetcher = this.#getFetcher();
     const fetcherOptions = this.#getFetcherOptions();
 
@@ -908,7 +1059,10 @@ export class ClientBuilder<
     const method = route.method;
 
     const baseUrl = this.#publicConfig.baseUrl ?? "";
-    const mountRoute = getMountRoute(this.#fragmentConfig);
+    const mountRoute = getMountRoute({
+      name: this.#fragmentConfig.name,
+      mountRoute: this.#publicConfig.mountRoute,
+    });
     const fetcher = this.#getFetcher();
     const fetcherOptions = this.#getFetcherOptions();
 
@@ -944,11 +1098,27 @@ export class ClientBuilder<
 
       let response: Response;
       try {
-        const requestOptions: RequestInit = {
+        const { body: preparedBody, headers: bodyHeaders } = prepareRequestBody(
+          body,
+          route.contentType,
+        );
+
+        // Merge headers: fetcherOptions headers + body-specific headers (e.g., Content-Type for JSON)
+        // For FormData, bodyHeaders is undefined and browser sets Content-Type with boundary automatically
+        const mergedHeaders = mergeRequestHeaders(
+          fetcherOptions?.headers as HeadersInit | undefined,
+          bodyHeaders,
+        );
+
+        const requestOptions: RequestInit & { duplex?: "half" } = {
           ...fetcherOptions,
           method,
-          body: body !== undefined ? JSON.stringify(body) : undefined,
+          body: preparedBody,
+          ...(mergedHeaders ? { headers: mergedHeaders } : {}),
         };
+        if (preparedBody instanceof ReadableStream) {
+          requestOptions.duplex = "half";
+        }
         response = await fetcher(url, requestOptions);
       } catch (error) {
         throw FragnoClientFetchError.fromUnknownFetchError(error);
@@ -1130,6 +1300,7 @@ export function createClientBuilder<
   THandlerThisContext extends RequestThisContext,
   TRequestStorage,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
+  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},
 >(
   definition: FragmentDefinition<
     TConfig,
@@ -1141,7 +1312,8 @@ export function createClientBuilder<
     TPrivateServices,
     TServiceThisContext,
     THandlerThisContext,
-    TRequestStorage
+    TRequestStorage,
+    TLinkedFragments
   >,
   publicConfig: FragnoPublicClientConfig,
   routesOrFactories: TRoutesOrFactories,
@@ -1166,7 +1338,10 @@ export function createClientBuilder<
     routes,
   };
 
-  const mountRoute = publicConfig.mountRoute ?? `/${definition.name}`;
+  const mountRoute = getMountRoute({
+    name: definition.name,
+    mountRoute: publicConfig.mountRoute,
+  });
   const mergedFetcherConfig = mergeFetcherConfigs(authorFetcherConfig, publicConfig.fetcherConfig);
   const fullPublicConfig = {
     ...publicConfig,

package/src/client/vue.test.ts

@@ -1,4 +1,4 @@
-import { test, expect, describe, vi, beforeEach, afterEach, assert } from "vitest";
+import { test, expect, describe, vi, beforeEach, afterEach, assert, expectTypeOf } from "vitest";
 import { type FragnoPublicClientConfig } from "./client";
 import { createClientBuilder } from "./client";
 import { defineRoute } from "../api/route";
@@ -6,9 +6,9 @@ import { defineFragment } from "../api/fragment-definition-builder";
 import { z } from "zod";
 import { refToAtom, useFragno } from "./vue";
 import { waitFor } from "@testing-library/vue";
-import { nextTick, ref, watch } from "vue";
+import { nextTick, ref, watch, effectScope } from "vue";
 import { FragnoClientUnknownApiError } from "./client-error";
-import { atom } from "nanostores";
+import { atom, computed, type ReadableAtom } from "nanostores";
 
 global.fetch = vi.fn();
 
@@ -752,3 +752,253 @@ describe("useFragno", () => {
     expect(typeof result.usePostAction).toBe("function");
   });
 });
+
+describe("useFragno - createStore", () => {
+  const clientConfig: FragnoPublicClientConfig = {
+    baseUrl: "http://localhost:3000",
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    (global.fetch as ReturnType<typeof vi.fn>).mockReset();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("FragnoVueStore type test - ReadableAtom fields", () => {
+    // Test that ReadableAtom fields are properly unwrapped to their value types
+    const stringAtom: ReadableAtom<string> = atom("hello");
+    const numberAtom: ReadableAtom<number> = atom(42);
+    const booleanAtom: ReadableAtom<boolean> = atom(true);
+    const objectAtom: ReadableAtom<{ count: number }> = atom({ count: 0 });
+    const arrayAtom: ReadableAtom<string[]> = atom(["a", "b", "c"]);
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useStore: cb.createStore({
+        message: stringAtom,
+        count: numberAtom,
+        isActive: booleanAtom,
+        data: objectAtom,
+        items: arrayAtom,
+      }),
+    };
+
+    const { useStore } = useFragno(client);
+
+    // Type assertions to ensure the types are correctly inferred
+    expectTypeOf(useStore).toExtend<
+      () => {
+        message: string;
+        count: number;
+        isActive: boolean;
+        data: { count: number };
+        items: string[];
+      }
+    >();
+
+    // Runtime test - need to run in effect scope for Vue reactivity
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useStore();
+      expect(result.message).toBe("hello");
+      expect(result.count).toBe(42);
+      expect(result.isActive).toBe(true);
+      expect(result.data).toEqual({ count: 0 });
+      expect(result.items).toEqual(["a", "b", "c"]);
+    });
+    scope.stop();
+  });
+
+  test("FragnoVueStore type test - computed stores", () => {
+    // Test that computed stores (which are also ReadableAtom) are properly unwrapped
+    const baseNumber = atom(10);
+    const doubled = computed(baseNumber, (n) => n * 2);
+    const tripled = computed(baseNumber, (n) => n * 3);
+    const combined = computed([doubled, tripled], (d, t) => ({ doubled: d, tripled: t }));
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useComputedValues: cb.createStore({
+        base: baseNumber,
+        doubled: doubled,
+        tripled: tripled,
+        combined: combined,
+      }),
+    };
+
+    const { useComputedValues } = useFragno(client);
+
+    // Type assertions
+    expectTypeOf(useComputedValues).toExtend<
+      () => {
+        base: number;
+        doubled: number;
+        tripled: number;
+        combined: { doubled: number; tripled: number };
+      }
+    >();
+
+    // Runtime test
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useComputedValues();
+      expect(result.base).toBe(10);
+      expect(result.doubled).toBe(20);
+      expect(result.tripled).toBe(30);
+      expect(result.combined).toEqual({ doubled: 20, tripled: 30 });
+    });
+    scope.stop();
+  });
+
+  test("FragnoVueStore type test - mixed store and non-store fields", () => {
+    // Test that non-store fields are passed through unchanged
+    const messageAtom: ReadableAtom<string> = atom("test");
+    const regularFunction = (x: number) => x * 2;
+    const regularObject = { foo: "bar", baz: 123 };
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useMixed: cb.createStore({
+        message: messageAtom,
+        multiply: regularFunction,
+        config: regularObject,
+        constant: 42,
+      }),
+    };
+
+    const { useMixed } = useFragno(client);
+
+    // Type assertions
+    expectTypeOf(useMixed).toExtend<
+      () => {
+        message: string;
+        multiply: (x: number) => number;
+        config: { foo: string; baz: number };
+        constant: number;
+      }
+    >();
+
+    // Runtime test
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useMixed();
+      expect(result.message).toBe("test");
+      expect(result.multiply(5)).toBe(10);
+      expect(result.config).toEqual({ foo: "bar", baz: 123 });
+      expect(result.constant).toBe(42);
+    });
+    scope.stop();
+  });
+
+  test("FragnoVueStore type test - single store vs object with stores", () => {
+    // Test that a single store is unwrapped directly
+    const singleAtom: ReadableAtom<string> = atom("single");
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+
+    // Single store case
+    const clientSingle = {
+      useSingle: cb.createStore(singleAtom),
+    };
+    const { useSingle } = useFragno(clientSingle);
+    expectTypeOf(useSingle).toExtend<() => string>();
+
+    // Object with stores case
+    const clientObject = {
+      useObject: cb.createStore({
+        value: singleAtom,
+      }),
+    };
+    const { useObject } = useFragno(clientObject);
+    expectTypeOf(useObject).toExtend<() => { value: string }>();
+
+    // Runtime test
+    const scope = effectScope();
+    scope.run(() => {
+      const singleResult = useSingle();
+      expect(singleResult).toBe("single");
+
+      const objectResult = useObject();
+      expect(objectResult).toEqual({ value: "single" });
+    });
+    scope.stop();
+  });
+
+  test("FragnoVueStore type test - complex nested atoms", () => {
+    // Test complex nested structures with atoms
+    type User = { id: number; name: string; email: string };
+    type Settings = { theme: "light" | "dark"; notifications: boolean };
+
+    const userAtom: ReadableAtom<User> = atom({ id: 1, name: "John", email: "john@example.com" });
+    const settingsAtom: ReadableAtom<Settings> = atom({ theme: "light", notifications: true });
+    const loadingAtom: ReadableAtom<boolean> = atom(false);
+    const errorAtom: ReadableAtom<string | null> = atom(null);
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useAppState: cb.createStore({
+        user: userAtom,
+        settings: settingsAtom,
+        loading: loadingAtom,
+        error: errorAtom,
+      }),
+    };
+
+    const { useAppState } = useFragno(client);
+
+    // Type assertions for complex nested structure
+    expectTypeOf(useAppState).toExtend<
+      () => {
+        user: User;
+        settings: Settings;
+        loading: boolean;
+        error: string | null;
+      }
+    >();
+
+    // Runtime test
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useAppState();
+      expect(result.user).toEqual({ id: 1, name: "John", email: "john@example.com" });
+      expect(result.settings).toEqual({ theme: "light", notifications: true });
+      expect(result.loading).toBe(false);
+      expect(result.error).toBeNull();
+    });
+    scope.stop();
+  });
+
+  test("FragnoVueStore - reactivity with atom updates", async () => {
+    // Test that stores are reactive and update when atoms change
+    const countAtom = atom(0);
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useCounter: cb.createStore({
+        count: countAtom,
+      }),
+    };
+
+    const { useCounter } = useFragno(client);
+
+    const scope = effectScope();
+    let result: { count: number } | undefined;
+    scope.run(() => {
+      result = useCounter();
+      expect(result.count).toBe(0);
+    });
+
+    // Update the atom
+    countAtom.set(5);
+
+    // Re-run in scope to get updated value
+    scope.run(() => {
+      result = useCounter();
+      expect(result.count).toBe(5);
+    });
+
+    scope.stop();
+  });
+});

package/src/client/vue.ts

@@ -6,9 +6,12 @@ import type { NonGetHTTPMethod } from "../api/api";
 import {
   isGetHook,
   isMutatorHook,
+  isStore,
   type FragnoClientMutatorData,
   type FragnoClientHookData,
+  type FragnoStoreData,
 } from "./client";
+import { isReadableAtom } from "../util/nanostores";
 import type { FragnoClientError } from "./client-error";
 import type { MaybeExtractPathParamsOrWiden, QueryParamsHint } from "../api/internal/path";
 import type { InferOr } from "../util/types-util";
@@ -46,6 +49,15 @@ export type FragnoVueMutator<
   data: Ref<InferOr<TOutputSchema, undefined>>;
 };
 
+/**
+ * Type helper that unwraps any Store fields of the object into StoreValues
+ */
+export type FragnoVueStore<T extends object> = () => T extends Store<infer TStore>
+  ? StoreValue<TStore>
+  : {
+      [K in keyof T]: T[K] extends Store ? StoreValue<T[K]> : T[K];
+    };
+
 /**
  * Converts a Vue Ref to a NanoStore Atom.
  *
@@ -181,6 +193,33 @@ function createVueMutator<
   };
 }
 
+// Helper function to create a Vue composable from a store
+function createVueStore<const T extends object>(hook: FragnoStoreData<T>): FragnoVueStore<T> {
+  if (isReadableAtom(hook.obj)) {
+    return (() => useStore(hook.obj as Store).value) as FragnoVueStore<T>;
+  }
+
+  return (() => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result: any = {};
+
+    for (const key in hook.obj) {
+      if (!Object.prototype.hasOwnProperty.call(hook.obj, key)) {
+        continue;
+      }
+
+      const value = hook.obj[key];
+      if (isReadableAtom(value)) {
+        result[key] = useStore(value).value;
+      } else {
+        result[key] = value;
+      }
+    }
+
+    return result;
+  }) as FragnoVueStore<T>;
+}
+
 export function useFragno<T extends Record<string, unknown>>(
   clientObj: T,
 ): {
@@ -201,7 +240,9 @@ export function useFragno<T extends Record<string, unknown>>(
           infer TQueryParameters
         >
       ? FragnoVueMutator<M, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>
-      : T[K];
+      : T[K] extends FragnoStoreData<infer TStoreObj>
+        ? FragnoVueStore<TStoreObj>
+        : T[K];
 } {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const result = {} as any;
@@ -216,6 +257,8 @@ export function useFragno<T extends Record<string, unknown>>(
       result[key] = createVueHook(hook);
     } else if (isMutatorHook(hook)) {
       result[key] = createVueMutator(hook);
+    } else if (isStore(hook)) {
+      result[key] = createVueStore(hook);
     } else {
       // Pass through non-hook values unchanged
       result[key] = hook;

package/src/internal/trace-context.ts

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type FragnoCoreTraceEvent =
+  | {
+      type: "route-input";
+      method: string;
+      path: string;
+      pathParams: Record<string, string>;
+      queryParams: [string, string][];
+      headers: [string, string][];
+      body: unknown;
+    }
+  | {
+      type: "middleware-decision";
+      method: string;
+      path: string;
+      outcome: "allow" | "deny";
+      status?: number;
+    };
+
+export type FragnoTraceRecorder = (event: FragnoCoreTraceEvent) => void;
+
+const traceStorage = new AsyncLocalStorage<FragnoTraceRecorder>();
+
+export const runWithTraceRecorder = <T>(recorder: FragnoTraceRecorder, callback: () => T): T =>
+  traceStorage.run(recorder, callback);
+
+export const getTraceRecorder = (): FragnoTraceRecorder | undefined => traceStorage.getStore();
+
+export const recordTraceEvent = (event: FragnoCoreTraceEvent): void => {
+  const recorder = traceStorage.getStore();
+  if (recorder) {
+    recorder(event);
+  }
+};