@fragno-dev/core 0.1.11 → 0.2.2

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,

package/src/client/react.test.ts

@@ -1,15 +1,19 @@
 import { test, expect, describe, vi, beforeEach, afterEach, expectTypeOf } from "vitest";
-import { renderHook, act, waitFor } from "@testing-library/react";
+
 import { atom, computed, type ReadableAtom } from "nanostores";
+import { StrictMode, createElement } from "react";
 import { z } from "zod";
-import { createClientBuilder } from "./client";
-import { useFragno, useStore, type FragnoReactStore } from "./react";
-import { defineRoute } from "../api/route";
+
+import type { FetcherStore } from "@nanostores/query";
+import { renderHook, act, waitFor } from "@testing-library/react";
+
 import { defineFragment } from "../api/fragment-definition-builder";
+import { RequestOutputContext } from "../api/request-output-context";
+import { defineRoute } from "../api/route";
+import { createClientBuilder } from "./client";
 import type { FragnoPublicClientConfig } from "./client";
 import { FragnoClientFetchNetworkError, type FragnoClientError } from "./client-error";
-import { RequestOutputContext } from "../api/request-output-context";
-import type { FetcherStore } from "@nanostores/query";
+import { useFragno, useStore, type FragnoReactStore } from "./react";
 
 // Mock fetch globally
 global.fetch = vi.fn();
@@ -875,6 +879,172 @@ describe("useFragno - createStore", () => {
     expect(result.current.error).toBeNull();
   });
 
+  test("createStore supports factory callbacks with cleanup", async () => {
+    const disposeOne = vi.fn();
+    const disposeTwo = vi.fn();
+    const factory = vi.fn(({ path }: { path: { sessionId: string } }) => ({
+      sessionId: atom(path.sessionId),
+      sendMessage: (text: string) => text,
+      [Symbol.dispose]: path.sessionId === "1" ? disposeOne : disposeTwo,
+    }));
+
+    const createSessionStore = (args: { path: { sessionId: string } }) => factory(args);
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useSession: cb.createStore(createSessionStore),
+    };
+
+    const { useSession } = useFragno(client);
+
+    expectTypeOf(useSession).toExtend<
+      (args: { path: { sessionId: string } }) => {
+        sessionId: string;
+        sendMessage: (text: string) => string;
+      }
+    >();
+
+    const { result, rerender, unmount } = renderHook(
+      ({ sessionId }) => useSession({ path: { sessionId } }),
+      { initialProps: { sessionId: "1" } },
+    );
+
+    expect(result.current.sessionId).toBe("1");
+    expect(result.current.sendMessage("hi")).toBe("hi");
+    expect(factory).toHaveBeenCalledTimes(1);
+
+    rerender({ sessionId: "1" });
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(disposeOne).not.toHaveBeenCalled();
+
+    rerender({ sessionId: "2" });
+    expect(result.current.sessionId).toBe("2");
+    expect(factory).toHaveBeenCalledTimes(2);
+
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(disposeOne).toHaveBeenCalledTimes(1);
+    expect(disposeTwo).not.toHaveBeenCalled();
+
+    unmount();
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(disposeTwo).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not dispose and recreate factory stores when rerendered with equivalent Date-backed args", () => {
+    const dispose = vi.fn();
+    const factory = vi.fn(
+      ({
+        path,
+        initialData,
+      }: {
+        path: { sessionId: string };
+        initialData: {
+          createdAt: Date;
+          updatedAt: Date;
+          trace: Array<{ createdAt: Date; type: string }>;
+        };
+      }) => ({
+        sessionId: path.sessionId,
+        traceCount: initialData.trace.length,
+        [Symbol.dispose]: dispose,
+      }),
+    );
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useSession: cb.createStore(factory),
+    };
+
+    const { useSession } = useFragno(client);
+
+    const buildInitialData = () => ({
+      createdAt: new Date("2026-01-01T00:00:00.000Z"),
+      updatedAt: new Date("2026-01-01T00:00:01.000Z"),
+      trace: [{ createdAt: new Date("2026-01-01T00:00:02.000Z"), type: "message_start" }],
+    });
+
+    const { result, rerender } = renderHook(
+      ({ initialData }) => useSession({ path: { sessionId: "session-1" }, initialData }),
+      {
+        initialProps: {
+          initialData: buildInitialData(),
+        },
+      },
+    );
+
+    expect(result.current.sessionId).toBe("session-1");
+    expect(result.current.traceCount).toBe(1);
+    expect(factory).toHaveBeenCalledTimes(1);
+
+    rerender({ initialData: buildInitialData() });
+
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(dispose).not.toHaveBeenCalled();
+  });
+
+  test("does not dispose a factory store during StrictMode remount probing", async () => {
+    const dispose = vi.fn();
+    const factory = vi.fn(({ path }: { path: { sessionId: string } }) => ({
+      sessionId: path.sessionId,
+      [Symbol.dispose]: dispose,
+    }));
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useSession: cb.createStore(factory),
+    };
+
+    const { useSession } = useFragno(client);
+
+    const { result, unmount } = renderHook(() => useSession({ path: { sessionId: "session-1" } }), {
+      wrapper: ({ children }) => createElement(StrictMode, null, children),
+    });
+
+    expect(result.current.sessionId).toBe("session-1");
+
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(dispose).not.toHaveBeenCalled();
+
+    unmount();
+
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("createStore preserves class methods that rely on private fields", () => {
+    const builder = createClientBuilder(
+      defineFragment("test-fragment-private-store"),
+      clientConfig,
+      [],
+    );
+
+    class SessionStore {
+      sessionId = atom("initial");
+      #prefix: string;
+
+      constructor(sessionId: string) {
+        this.sessionId.set(sessionId);
+        this.#prefix = `session:${sessionId}`;
+      }
+
+      start() {
+        return `${this.#prefix}:start`;
+      }
+    }
+
+    const client = {
+      useSession: builder.createStore(
+        ({ path }: { path: { sessionId: string } }) => new SessionStore(path.sessionId),
+      ),
+    };
+
+    const { useSession } = useFragno(client);
+    const { result } = renderHook(() => useSession({ path: { sessionId: "abc" } }));
+
+    expect(result.current.sessionId).toBe("abc");
+    expect(result.current.start()).toBe("session:abc:start");
+  });
+
   test("Derived from streaming route", async () => {
     const streamFragmentDefinition = defineFragment("stream-fragment");
     const streamRoutes = [

package/src/client/react.ts

@@ -1,13 +1,17 @@
+import { listenKeys, type ReadableAtom, type Store, type StoreValue } from "nanostores";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  type DependencyList,
+} from "react";
+
 import type { FetcherValue } from "@nanostores/query";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { listenKeys, type ReadableAtom, type Store, type StoreValue } from "nanostores";
-import { useCallback, useMemo, useRef, useSyncExternalStore, type DependencyList } from "react";
+
 import type { NonGetHTTPMethod } from "../api/api";
-import type { FragnoClientMutatorData, FragnoClientHookData } from "./client";
-import { isGetHook, isMutatorHook, isStore, type FragnoStoreData } from "./client";
-import type { FragnoClientError } from "./client-error";
-import { hydrateFromWindow } from "../util/ssr";
-import type { InferOr } from "../util/types-util";
 import type {
   ExtractPathParamsOrWiden,
   HasPathParams,
@@ -15,6 +19,18 @@ import type {
   QueryParamsHint,
 } from "../api/internal/path";
 import { isReadableAtom } from "../util/nanostores";
+import { hydrateFromWindow } from "../util/ssr";
+import type { InferOr } from "../util/types-util";
+import type { FragnoClientMutatorData, FragnoClientHookData } from "./client";
+import {
+  isGetHook,
+  isMutatorHook,
+  isStore,
+  type FragnoStoreData,
+  type FragnoStoreFactoryData,
+  type FragnoStoreObjectData,
+} from "./client";
+import type { FragnoClientError } from "./client-error";
 
 export type FragnoReactHook<
   _TMethod extends "GET",
@@ -103,36 +119,213 @@ function createReactMutator<
 /**
  * Type helper that unwraps any Store fields of the object into StoreValues
  */
-export type FragnoReactStore<T extends object> = () => T extends Store<infer TStore>
-  ? StoreValue<TStore>
-  : {
-      [K in keyof T]: T[K] extends Store ? StoreValue<T[K]> : T[K];
-    };
+type FragnoReactStoreValue<T extends object> =
+  T extends Store<infer TStore>
+    ? StoreValue<TStore>
+    : {
+        [K in keyof T]: T[K] extends Store ? StoreValue<T[K]> : T[K];
+      };
 
-function createReactStore<const T extends object>(hook: FragnoStoreData<T>): FragnoReactStore<T> {
-  if (isReadableAtom(hook.obj)) {
-    return () => useStore(hook.obj as Store);
+export type FragnoReactStore<T extends object, TArgs extends unknown[] = []> = (
+  ...args: TArgs
+) => FragnoReactStoreValue<T>;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (!value || typeof value !== "object") {
+    return false;
   }
 
-  return () => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const result: any = {};
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+const areStoreFactoryValuesEqual = (left: unknown, right: unknown): boolean => {
+  if (Object.is(left, right)) {
+    return true;
+  }
+
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return (
+      left.length === right.length &&
+      left.every((value, index) => areStoreFactoryValuesEqual(value, right[index]))
+    );
+  }
+
+  if (left instanceof Date && right instanceof Date) {
+    return left.getTime() === right.getTime();
+  }
+
+  if (isReadableAtom(left) || isReadableAtom(right)) {
+    return left === right;
+  }
+
+  if (typeof left === "function" || typeof right === "function") {
+    return left === right;
+  }
+
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return (
+      leftKeys.length === rightKeys.length &&
+      leftKeys.every(
+        (key, index) =>
+          key === rightKeys[index] && areStoreFactoryValuesEqual(left[key], right[key]),
+      )
+    );
+  }
+
+  return false;
+};
+
+const areStoreFactoryArgsEqual = (left: unknown[], right: unknown[]) =>
+  left.length === right.length &&
+  left.every((value, index) => areStoreFactoryValuesEqual(value, right[index]));
+
+const getStoreDisposer = (value: object): (() => void) | undefined => {
+  const disposer = (value as { [Symbol.dispose]?: (() => void) | undefined })[Symbol.dispose];
+  return typeof disposer === "function" ? disposer.bind(value) : undefined;
+};
 
-    for (const key in hook.obj) {
-      if (!Object.prototype.hasOwnProperty.call(hook.obj, key)) {
-        continue;
+const createReactStoreObjectView = <T extends object>(
+  value: T,
+  getAtomValue: (store: Store<unknown>) => unknown,
+): FragnoReactStoreValue<T> => {
+  const atomValues = new Map<Store<unknown>, unknown>();
+  const boundMethods = new Map<PropertyKey, unknown>();
+
+  return new Proxy(value, {
+    get(target, property, _receiver) {
+      const propertyValue = Reflect.get(target, property, target);
+
+      if (isReadableAtom(propertyValue)) {
+        if (atomValues.has(propertyValue)) {
+          return atomValues.get(propertyValue);
+        }
+
+        const atomValue = getAtomValue(propertyValue);
+        atomValues.set(propertyValue, atomValue);
+        return atomValue;
       }
 
-      const value = hook.obj[key];
-      if (isReadableAtom(value)) {
-        result[key] = useStore(value);
-      } else {
-        result[key] = value;
+      if (typeof propertyValue === "function") {
+        if (boundMethods.has(property)) {
+          return boundMethods.get(property);
+        }
+
+        const boundMethod = propertyValue.bind(target);
+        boundMethods.set(property, boundMethod);
+        return boundMethod;
       }
-    }
 
-    return result;
+      return propertyValue;
+    },
+  }) as FragnoReactStoreValue<T>;
+};
+
+function unwrapReactStoreValueOnServer<T extends object>(value: T): FragnoReactStoreValue<T> {
+  if (isReadableAtom(value)) {
+    return value.get() as FragnoReactStoreValue<T>;
+  }
+
+  return createReactStoreObjectView(value, (store) => store.get());
+}
+
+function unwrapReactStoreValue<T extends object>(value: T): FragnoReactStoreValue<T> {
+  if (isReadableAtom(value)) {
+    return useStore(value as Store) as FragnoReactStoreValue<T>;
+  }
+
+  const keys = Object.keys(value);
+  const atomEntries = keys.flatMap((key) => {
+    const fieldValue = value[key as keyof T];
+    return isReadableAtom(fieldValue)
+      ? ([[key, fieldValue]] as Array<[string, Store<unknown>]>)
+      : [];
+  });
+  const snapshotRef = useRef<unknown[]>(atomEntries.map(([, store]) => store.get()));
+
+  const getSnapshot = () => {
+    const nextSnapshot = atomEntries.map(([, store]) => store.get());
+    const previousSnapshot = snapshotRef.current;
+    if (
+      previousSnapshot.length === nextSnapshot.length &&
+      previousSnapshot.every((entry, index) => Object.is(entry, nextSnapshot[index]))
+    ) {
+      return previousSnapshot;
+    }
+    snapshotRef.current = nextSnapshot;
+    return nextSnapshot;
   };
+
+  const atomValues = useSyncExternalStore(
+    (onStoreChange) => {
+      const unsubscribes = atomEntries.map(([, store]) => store.listen(onStoreChange));
+      return () => {
+        for (const unsubscribe of unsubscribes) {
+          unsubscribe();
+        }
+      };
+    },
+    getSnapshot,
+    getSnapshot,
+  );
+
+  return useMemo(
+    () =>
+      createReactStoreObjectView(value, (store) => {
+        const atomIndex = atomEntries.findIndex(([, entryStore]) => entryStore === store);
+        return atomIndex === -1 ? store.get() : atomValues[atomIndex];
+      }),
+    [value, atomEntries, atomValues],
+  );
+}
+
+function createReactStore<const T extends object, const TArgs extends unknown[]>(
+  hook: FragnoStoreData<T, TArgs>,
+): FragnoReactStore<T, TArgs> {
+  return ((...args: TArgs) => {
+    const stableArgsRef = useRef<TArgs>(args);
+    const pendingDisposalsRef = useRef<Map<object, ReturnType<typeof setTimeout>>>(new Map());
+    if (!areStoreFactoryArgsEqual(stableArgsRef.current, args)) {
+      stableArgsRef.current = args;
+    }
+
+    const value = useMemo(() => {
+      if ("factory" in hook) {
+        return hook.factory(...stableArgsRef.current);
+      }
+
+      return hook.obj;
+    }, [hook, stableArgsRef.current]);
+
+    useEffect(() => {
+      const disposer = getStoreDisposer(value);
+      const pendingTimeout = pendingDisposalsRef.current.get(value);
+      if (pendingTimeout !== undefined) {
+        clearTimeout(pendingTimeout);
+        pendingDisposalsRef.current.delete(value);
+      }
+
+      return () => {
+        if (!disposer) {
+          return;
+        }
+
+        const timeoutId = setTimeout(() => {
+          pendingDisposalsRef.current.delete(value);
+          disposer();
+        }, 0);
+        pendingDisposalsRef.current.set(value, timeoutId);
+      };
+    }, [value]);
+
+    if (typeof window === "undefined") {
+      return unwrapReactStoreValueOnServer(value);
+    }
+
+    return unwrapReactStoreValue(value);
+  }) as FragnoReactStore<T, TArgs>;
 }
 
 export function useFragno<T extends Record<string, unknown>>(
@@ -155,9 +348,11 @@ export function useFragno<T extends Record<string, unknown>>(
           infer TQueryParameters
         >
       ? FragnoReactMutator<TMethod, TPath, TInput, TOutput, TError, TQueryParameters>
-      : T[K] extends FragnoStoreData<infer TStoreObj>
-        ? FragnoReactStore<TStoreObj>
-        : T[K];
+      : T[K] extends FragnoStoreObjectData<infer TStoreObj>
+        ? FragnoReactStore<TStoreObj, []>
+        : T[K] extends FragnoStoreFactoryData<infer TStoreObj, infer TStoreArgs>
+          ? FragnoReactStore<TStoreObj, TStoreArgs>
+          : T[K];
 } {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const result = {} as any; // We need one any cast here due to TypeScript's limitations with mapped types

package/src/client/solid.test.ts

@@ -1,13 +1,15 @@
-import { test, expect, describe, vi, beforeEach, afterEach, assert } from "vitest";
+import { test, expect, describe, vi, beforeEach, afterEach, assert, expectTypeOf } from "vitest";
+
 import { atom, computed, type ReadableAtom } from "nanostores";
+import { createSignal, createRoot } from "solid-js";
 import { z } from "zod";
-import { createClientBuilder } from "./client";
-import { useFragno, accessorToAtom, isAccessor } from "./solid";
-import { defineRoute } from "../api/route";
+
 import { defineFragment } from "../api/fragment-definition-builder";
+import { defineRoute } from "../api/route";
+import { createClientBuilder } from "./client";
 import type { FragnoPublicClientConfig } from "./client";
 import { FragnoClientUnknownApiError } from "./client-error";
-import { createSignal, createRoot } from "solid-js";
+import { useFragno, accessorToAtom, isAccessor } from "./solid";
 
 // Mock fetch globally
 global.fetch = vi.fn();
@@ -819,6 +821,28 @@ describe("createSolidStore", () => {
     });
   });
 
+  test("should type and return zero-argument factory stores as callable", () => {
+    const countAtom: ReadableAtom<number> = atom(0);
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+
+    const client = {
+      useCounter: cb.createStore(() => countAtom),
+    };
+
+    createRoot((dispose) => {
+      const { useCounter } = useFragno(client);
+
+      expectTypeOf(useCounter).toExtend<() => () => number>();
+      expect(typeof useCounter).toBe("function");
+
+      const counter = useCounter();
+      expect(typeof counter).toBe("function");
+      expect(counter()).toBe(0);
+
+      dispose();
+    });
+  });
+
   test("should handle single atom as store", () => {
     const singleAtom: ReadableAtom<string> = atom("single");
     const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);