@fragno-dev/core 0.2.0 → 0.2.2

package/src/client/vanilla.test.ts

@@ -1,13 +1,15 @@
-import { test, expect, describe, vi, beforeEach, afterEach } from "vitest";
-import { atom } from "nanostores";
+import { test, expect, describe, vi, beforeEach, afterEach, expectTypeOf } from "vitest";
+
+import { atom, type ReadableAtom } from "nanostores";
 import { z } from "zod";
-import { createClientBuilder } from "./client";
-import { useFragno } from "./vanilla";
-import { defineRoute } from "../api/route";
+
 import { defineFragment } from "../api/fragment-definition-builder";
+import { defineRoute } from "../api/route";
+import { waitForAsyncIterator } from "../util/async";
+import { createClientBuilder } from "./client";
 import type { FragnoPublicClientConfig } from "./client";
 import { FragnoClientFetchNetworkError } from "./client-error";
-import { waitForAsyncIterator } from "../util/async";
+import { useFragno } from "./vanilla";
 
 // Mock fetch globally
 global.fetch = vi.fn();
@@ -620,6 +622,56 @@ describe("createVanillaMutator", () => {
   });
 });
 
+describe("useFragno - createStore", () => {
+  const clientConfig: FragnoPublicClientConfig = {
+    baseUrl: "http://localhost:3000",
+  };
+
+  test("unwraps store wrappers to the raw store object", () => {
+    const stringAtom = atom("hello");
+    const numberAtom = atom(42);
+    const cb = createClientBuilder(defineFragment("test-fragment-store"), clientConfig, []);
+    const client = {
+      useStore: cb.createStore({
+        message: stringAtom,
+        count: numberAtom,
+        constant: 7,
+      }),
+    };
+
+    const { useStore } = useFragno(client);
+
+    expectTypeOf(useStore).toExtend<{
+      message: typeof stringAtom;
+      count: typeof numberAtom;
+      constant: number;
+    }>();
+
+    if (!("obj" in client.useStore)) {
+      throw new Error("Expected object-backed store");
+    }
+
+    expect(useStore).toBe(client.useStore.obj);
+    expect(useStore.message.get()).toBe("hello");
+    expect(useStore.count.get()).toBe(42);
+    expect(useStore.constant).toBe(7);
+  });
+
+  test("unwraps single-store wrappers to the underlying atom", () => {
+    const singleAtom = atom("single");
+    const cb = createClientBuilder(defineFragment("test-fragment-single-store"), clientConfig, []);
+    const client = {
+      useSingle: cb.createStore(singleAtom),
+    };
+
+    const { useSingle } = useFragno(client);
+
+    expectTypeOf(useSingle).toExtend<typeof singleAtom>();
+    expect(useSingle).toBe(singleAtom);
+    expect(useSingle.get()).toBe("single");
+  });
+});
+
 describe("useFragno", () => {
   const testFragmentDefinition = defineFragment("test-fragment-useFragno");
   const testRoutes = [
@@ -771,6 +823,96 @@ describe("useFragno", () => {
   });
 });
 
+describe("createVanillaStore", () => {
+  const clientConfig: FragnoPublicClientConfig = {
+    baseUrl: "http://localhost:3000",
+  };
+
+  test("should support createStore factory callbacks", () => {
+    const dispose = vi.fn();
+    const builder = createClientBuilder(defineFragment("test-fragment-store"), clientConfig, []);
+    const clientObj = {
+      useSession: builder.createStore(({ path }: { path: { sessionId: string } }) => ({
+        sessionId: atom(path.sessionId),
+        sendMessage: (text: string) => text,
+        [Symbol.dispose]: dispose,
+      })),
+    };
+
+    const { useSession } = useFragno(clientObj);
+    const session = useSession({ path: { sessionId: "abc" } });
+
+    expect(session.sessionId.get()).toBe("abc");
+    expect(session.sendMessage("hello")).toBe("hello");
+    expect(typeof session.destroy).toBe("function");
+
+    session.destroy?.();
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("should preserve prototype methods when adding destroy to factory store instances", () => {
+    const dispose = vi.fn();
+    const builder = createClientBuilder(
+      defineFragment("test-fragment-store-instance"),
+      clientConfig,
+      [],
+    );
+
+    class SessionStore {
+      sessionId: ReadableAtom<string>;
+
+      constructor(sessionId: string) {
+        this.sessionId = atom(sessionId);
+      }
+
+      sendMessage(text: string) {
+        return `${this.sessionId.get()}:${text}`;
+      }
+
+      [Symbol.dispose]() {
+        dispose();
+      }
+    }
+
+    const clientObj = {
+      useSession: builder.createStore(({ path }: { path: { sessionId: string } }) => {
+        return new SessionStore(path.sessionId);
+      }),
+    };
+
+    const { useSession } = useFragno(clientObj);
+    const session = useSession({ path: { sessionId: "abc" } });
+
+    expect(session).toBeInstanceOf(SessionStore);
+    expect(session.sendMessage("hello")).toBe("abc:hello");
+    expect(typeof session.destroy).toBe("function");
+    expect(Object.keys(session)).not.toContain("destroy");
+
+    session.destroy?.();
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("should type and return zero-argument factory stores as callable", () => {
+    const builder = createClientBuilder(
+      defineFragment("test-fragment-zero-arg-store"),
+      clientConfig,
+      [],
+    );
+    const countAtom = atom(0);
+    const clientObj = {
+      useCounter: builder.createStore(() => ({
+        count: countAtom,
+      })),
+    };
+
+    const { useCounter } = useFragno(clientObj);
+
+    expectTypeOf(useCounter).toExtend<() => { count: typeof countAtom }>();
+    expect(typeof useCounter).toBe("function");
+    expect(useCounter().count.get()).toBe(0);
+  });
+});
+
 describe("error handling", () => {
   const testFragmentDefinition = defineFragment("test-fragment-errors");
   const testRoutes = [

package/src/client/vanilla.ts

@@ -1,20 +1,26 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { ReadableAtom } from "nanostores";
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import type { NonGetHTTPMethod } from "../api/api";
+import type {
+  ExtractPathParamsOrWiden,
+  HasPathParams,
+  MaybeExtractPathParamsOrWiden,
+} from "../api/internal/path";
+import { createAsyncIteratorFromCallback } from "../util/async";
+import type { InferOr } from "../util/types-util";
 import {
   isGetHook,
   isMutatorHook,
+  isStore,
   type FragnoClientMutatorData,
   type FragnoClientHookData,
+  type FragnoStoreData,
+  type FragnoStoreFactoryData,
+  type FragnoStoreObjectData,
 } from "./client";
 import type { FragnoClientError } from "./client-error";
-import { createAsyncIteratorFromCallback } from "../util/async";
-import type { InferOr } from "../util/types-util";
-import type {
-  ExtractPathParamsOrWiden,
-  HasPathParams,
-  MaybeExtractPathParamsOrWiden,
-} from "../api/internal/path";
 
 export type StoreData<
   TOutputSchema extends StandardSchemaV1 | undefined,
@@ -213,6 +219,48 @@ function createVanillaMutator<
   };
 }
 
+export type FragnoVanillaStore<T extends object, TArgs extends unknown[] = []> = TArgs extends []
+  ? T
+  : (...args: TArgs) => T & { destroy?: () => void };
+
+export type FragnoVanillaStoreFromData<TStore> = TStore extends {
+  factory: (...args: infer TArgs) => infer TObject extends object;
+}
+  ? (...args: TArgs) => TObject & { destroy?: () => void }
+  : TStore extends { obj: infer TObject extends object }
+    ? TObject
+    : never;
+
+const getStoreDisposer = (value: object): (() => void) | undefined => {
+  const disposer = (value as { [Symbol.dispose]?: (() => void) | undefined })[Symbol.dispose];
+  return typeof disposer === "function" ? disposer.bind(value) : undefined;
+};
+
+function createVanillaStore<const TStore extends FragnoStoreData<object, unknown[]>>(
+  hook: TStore,
+): FragnoVanillaStoreFromData<TStore> {
+  if ("obj" in hook) {
+    return hook.obj as FragnoVanillaStoreFromData<TStore>;
+  }
+
+  return ((...args: Parameters<typeof hook.factory>) => {
+    const value = hook.factory(...args);
+    const disposer = getStoreDisposer(value);
+    if (!disposer) {
+      return value as ReturnType<typeof hook.factory> & { destroy?: () => void };
+    }
+
+    Object.defineProperty(value, "destroy", {
+      value: disposer,
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    });
+
+    return value as ReturnType<typeof hook.factory> & { destroy?: () => void };
+  }) as FragnoVanillaStoreFromData<TStore>;
+}
+
 export function useFragno<T extends Record<string, unknown>>(
   clientObj: T,
 ): {
@@ -240,7 +288,11 @@ export function useFragno<T extends Record<string, unknown>>(
           TErrorCode,
           TQueryParameters
         >
-      : T[K];
+      : T[K] extends FragnoStoreObjectData<infer TStoreObj>
+        ? TStoreObj
+        : T[K] extends FragnoStoreFactoryData<infer TStoreObj, infer TStoreArgs>
+          ? (...args: TStoreArgs) => TStoreObj & { destroy?: () => void }
+          : 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
@@ -255,6 +307,8 @@ export function useFragno<T extends Record<string, unknown>>(
       result[key] = createVanillaListeners(hook);
     } else if (isMutatorHook(hook)) {
       result[key] = createVanillaMutator(hook);
+    } else if (isStore(hook)) {
+      result[key] = createVanillaStore(hook);
     } else {
       // Pass through non-hook values unchanged
       result[key] = hook;

package/src/client/vue.test.ts

@@ -1,14 +1,17 @@
 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";
-import { defineFragment } from "../api/fragment-definition-builder";
+
+import { atom, computed, type ReadableAtom } from "nanostores";
+import { nextTick, ref, watch, effectScope } from "vue";
 import { z } from "zod";
-import { refToAtom, useFragno } from "./vue";
+
 import { waitFor } from "@testing-library/vue";
-import { nextTick, ref, watch, effectScope } from "vue";
+
+import { defineFragment } from "../api/fragment-definition-builder";
+import { defineRoute } from "../api/route";
+import { type FragnoPublicClientConfig } from "./client";
+import { createClientBuilder } from "./client";
 import { FragnoClientUnknownApiError } from "./client-error";
-import { atom, computed, type ReadableAtom } from "nanostores";
+import { refToAtom, useFragno } from "./vue";
 
 global.fetch = vi.fn();
 
@@ -768,7 +771,7 @@ describe("useFragno - createStore", () => {
   });
 
   test("FragnoVueStore type test - ReadableAtom fields", () => {
-    // Test that ReadableAtom fields are properly unwrapped to their value types
+    // Test that ReadableAtom fields are exposed as reactive refs
     const stringAtom: ReadableAtom<string> = atom("hello");
     const numberAtom: ReadableAtom<number> = atom(42);
     const booleanAtom: ReadableAtom<boolean> = atom(true);
@@ -788,32 +791,27 @@ describe("useFragno - createStore", () => {
 
     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"]);
+
+      expectTypeOf(result.message.value).toEqualTypeOf<string>();
+      expectTypeOf(result.count.value).toEqualTypeOf<number>();
+      expectTypeOf(result.isActive.value).toEqualTypeOf<boolean>();
+      expectTypeOf(result.data.value.count).toEqualTypeOf<number>();
+      expectTypeOf(result.items.value).toExtend<readonly string[]>();
+
+      expect(result.message.value).toBe("hello");
+      expect(result.count.value).toBe(42);
+      expect(result.isActive.value).toBe(true);
+      expect(result.data.value).toEqual({ count: 0 });
+      expect(result.items.value).toEqual(["a", "b", "c"]);
     });
     scope.stop();
   });
 
   test("FragnoVueStore type test - computed stores", () => {
-    // Test that computed stores (which are also ReadableAtom) are properly unwrapped
+    // Test that computed stores (which are also ReadableAtom) are exposed as refs
     const baseNumber = atom(10);
     const doubled = computed(baseNumber, (n) => n * 2);
     const tripled = computed(baseNumber, (n) => n * 3);
@@ -831,30 +829,26 @@ describe("useFragno - createStore", () => {
 
     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 });
+
+      expectTypeOf(result.base.value).toEqualTypeOf<number>();
+      expectTypeOf(result.doubled.value).toEqualTypeOf<number>();
+      expectTypeOf(result.tripled.value).toEqualTypeOf<number>();
+      expectTypeOf(result.combined.value.doubled).toEqualTypeOf<number>();
+      expectTypeOf(result.combined.value.tripled).toEqualTypeOf<number>();
+
+      expect(result.base.value).toBe(10);
+      expect(result.doubled.value).toBe(20);
+      expect(result.tripled.value).toBe(30);
+      expect(result.combined.value).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
+    // Test that store fields are refs and 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 };
@@ -871,21 +865,19 @@ describe("useFragno - createStore", () => {
 
     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");
+
+      expectTypeOf(result.message.value).toEqualTypeOf<string>();
+      expectTypeOf(result.multiply).toExtend<(x: number) => number>();
+      expectTypeOf(result.config.foo).toEqualTypeOf<string>();
+      expectTypeOf(result.config.baz).toEqualTypeOf<number>();
+      expectTypeOf(result.constant).toExtend<number>();
+
+      expect(result.message.value).toBe("test");
+      expect(result.multiply).toBe(regularFunction);
+      expect(result.config).toBe(regularObject);
       expect(result.multiply(5)).toBe(10);
       expect(result.config).toEqual({ foo: "bar", baz: 123 });
       expect(result.constant).toBe(42);
@@ -894,7 +886,7 @@ describe("useFragno - createStore", () => {
   });
 
   test("FragnoVueStore type test - single store vs object with stores", () => {
-    // Test that a single store is unwrapped directly
+    // Test that a single store is exposed as a ref directly
     const singleAtom: ReadableAtom<string> = atom("single");
     const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
 
@@ -903,7 +895,6 @@ describe("useFragno - createStore", () => {
       useSingle: cb.createStore(singleAtom),
     };
     const { useSingle } = useFragno(clientSingle);
-    expectTypeOf(useSingle).toExtend<() => string>();
 
     // Object with stores case
     const clientObject = {
@@ -912,16 +903,17 @@ describe("useFragno - createStore", () => {
       }),
     };
     const { useObject } = useFragno(clientObject);
-    expectTypeOf(useObject).toExtend<() => { value: string }>();
 
-    // Runtime test
+    // Runtime and type test
     const scope = effectScope();
     scope.run(() => {
       const singleResult = useSingle();
-      expect(singleResult).toBe("single");
+      expectTypeOf(singleResult.value).toEqualTypeOf<string>();
+      expect(singleResult.value).toBe("single");
 
       const objectResult = useObject();
-      expect(objectResult).toEqual({ value: "single" });
+      expectTypeOf(objectResult.value.value).toEqualTypeOf<string>();
+      expect(objectResult.value.value).toBe("single");
     });
     scope.stop();
   });
@@ -948,30 +940,108 @@ describe("useFragno - createStore", () => {
 
     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();
+
+      expectTypeOf(result.user.value.id).toEqualTypeOf<number>();
+      expectTypeOf(result.user.value.name).toEqualTypeOf<string>();
+      expectTypeOf(result.settings.value.theme).toEqualTypeOf<"light" | "dark">();
+      expectTypeOf(result.settings.value.notifications).toEqualTypeOf<boolean>();
+      expectTypeOf(result.loading.value).toEqualTypeOf<boolean>();
+      expectTypeOf(result.error.value).toEqualTypeOf<string | null>();
+
+      expect(result.user.value).toEqual({ id: 1, name: "John", email: "john@example.com" });
+      expect(result.settings.value).toEqual({ theme: "light", notifications: true });
+      expect(result.loading.value).toBe(false);
+      expect(result.error.value).toBeNull();
     });
     scope.stop();
   });
 
-  test("FragnoVueStore - reactivity with atom updates", async () => {
-    // Test that stores are reactive and update when atoms change
+  test("FragnoVueStore - top-level atom stays reactive", async () => {
+    const countAtom = atom(0);
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useCounter: cb.createStore(countAtom),
+    };
+
+    const { useCounter } = useFragno(client);
+
+    const scope = effectScope();
+    const observed: number[] = [];
+
+    scope.run(() => {
+      const result = useCounter();
+      watch(
+        () => result.value,
+        (value) => {
+          observed.push(value);
+        },
+        { immediate: true },
+      );
+    });
+
+    countAtom.set(5);
+    await nextTick();
+
+    expect(observed).toEqual([0, 5]);
+
+    scope.stop();
+  });
+
+  test("FragnoVueStore - computed refs stay reactive", async () => {
+    const baseNumber = atom(2);
+    const doubled = computed(baseNumber, (n) => n * 2);
+    const combined = computed([baseNumber, doubled], (base, double) => ({ base, double }));
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useComputedValues: cb.createStore({
+        base: baseNumber,
+        doubled,
+        combined,
+      }),
+    };
+
+    const { useComputedValues } = useFragno(client);
+
+    const scope = effectScope();
+    const observedDoubled: number[] = [];
+    const observedCombined: Array<{ base: number; double: number }> = [];
+
+    scope.run(() => {
+      const result = useComputedValues();
+      watch(
+        () => result.doubled.value,
+        (value) => {
+          observedDoubled.push(value);
+        },
+        { immediate: true },
+      );
+      watch(
+        () => result.combined.value,
+        (value) => {
+          observedCombined.push(value);
+        },
+        { immediate: true },
+      );
+    });
+
+    baseNumber.set(3);
+    await nextTick();
+
+    expect(observedDoubled).toEqual([4, 6]);
+    expect(observedCombined).toEqual([
+      { base: 2, double: 4 },
+      { base: 3, double: 6 },
+    ]);
+
+    scope.stop();
+  });
+
+  test("FragnoVueStore - unsubscribes atom refs on scope disposal", async () => {
     const countAtom = atom(0);
 
     const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
@@ -984,21 +1054,90 @@ describe("useFragno - createStore", () => {
     const { useCounter } = useFragno(client);
 
     const scope = effectScope();
-    let result: { count: number } | undefined;
+    const observed: number[] = [];
+
     scope.run(() => {
-      result = useCounter();
-      expect(result.count).toBe(0);
+      const result = useCounter();
+      watch(
+        () => result.count.value,
+        (value) => {
+          observed.push(value);
+        },
+        { immediate: true },
+      );
     });
 
-    // Update the atom
+    expect(observed).toEqual([0]);
+
+    scope.stop();
     countAtom.set(5);
+    await nextTick();
+
+    expect(observed).toEqual([0]);
+  });
+
+  test("FragnoVueStore - factory stores dispose on scope disposal", () => {
+    const dispose = vi.fn();
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useSession: cb.createStore((sessionId: string) => ({
+        sessionId: atom(sessionId),
+        sendMessage: (text: string) => text,
+        [Symbol.dispose]: dispose,
+      })),
+    };
+
+    const { useSession } = useFragno(client);
+
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useSession("session-1");
+
+      expectTypeOf(result.sessionId.value).toEqualTypeOf<string>();
+      expect(result.sessionId.value).toBe("session-1");
+      expect(result.sendMessage("hi")).toBe("hi");
+    });
+
+    expect(dispose).not.toHaveBeenCalled();
+
+    scope.stop();
+
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("FragnoVueStore - reactivity with atom updates", async () => {
+    // Test that returned refs stay reactive 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();
+    const observed: number[] = [];
 
-    // Re-run in scope to get updated value
     scope.run(() => {
-      result = useCounter();
-      expect(result.count).toBe(5);
+      const result = useCounter();
+      watch(
+        () => result.count.value,
+        (value) => {
+          observed.push(value);
+        },
+        { immediate: true },
+      );
     });
 
+    countAtom.set(5);
+    await nextTick();
+
+    expect(observed).toEqual([0, 5]);
+
     scope.stop();
   });
 });