@fragno-dev/core 0.1.11 → 0.2.2

package/src/client/vue.test.ts

@@ -1,14 +1,17 @@
-import { test, expect, describe, vi, beforeEach, afterEach, assert } from "vitest";
-import { type FragnoPublicClientConfig } from "./client";
-import { createClientBuilder } from "./client";
-import { defineRoute } from "../api/route";
-import { defineFragment } from "../api/fragment-definition-builder";
+import { test, expect, describe, vi, beforeEach, afterEach, assert, expectTypeOf } from "vitest";
+
+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 } 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 } from "nanostores";
+import { refToAtom, useFragno } from "./vue";
 
 global.fetch = vi.fn();
 
@@ -752,3 +755,389 @@ 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 exposed as reactive refs
+    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);
+
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useStore();
+
+      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 exposed as refs
+    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);
+
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useComputedValues();
+
+      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 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 };
+
+    const cb = createClientBuilder(defineFragment("test-fragment"), clientConfig, []);
+    const client = {
+      useMixed: cb.createStore({
+        message: messageAtom,
+        multiply: regularFunction,
+        config: regularObject,
+        constant: 42,
+      }),
+    };
+
+    const { useMixed } = useFragno(client);
+
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useMixed();
+
+      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);
+    });
+    scope.stop();
+  });
+
+  test("FragnoVueStore type test - single store vs object with stores", () => {
+    // Test that a single store is exposed as a ref 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);
+
+    // Object with stores case
+    const clientObject = {
+      useObject: cb.createStore({
+        value: singleAtom,
+      }),
+    };
+    const { useObject } = useFragno(clientObject);
+
+    // Runtime and type test
+    const scope = effectScope();
+    scope.run(() => {
+      const singleResult = useSingle();
+      expectTypeOf(singleResult.value).toEqualTypeOf<string>();
+      expect(singleResult.value).toBe("single");
+
+      const objectResult = useObject();
+      expectTypeOf(objectResult.value.value).toEqualTypeOf<string>();
+      expect(objectResult.value.value).toBe("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);
+
+    const scope = effectScope();
+    scope.run(() => {
+      const result = useAppState();
+
+      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 - 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, []);
+    const client = {
+      useCounter: cb.createStore({
+        count: countAtom,
+      }),
+    };
+
+    const { useCounter } = useFragno(client);
+
+    const scope = effectScope();
+    const observed: number[] = [];
+
+    scope.run(() => {
+      const result = useCounter();
+      watch(
+        () => result.count.value,
+        (value) => {
+          observed.push(value);
+        },
+        { immediate: true },
+      );
+    });
+
+    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[] = [];
+
+    scope.run(() => {
+      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();
+  });
+});

package/src/client/vue.ts

@@ -1,17 +1,24 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { atom, type ReadableAtom, type Store, type StoreValue } from "nanostores";
 import type { DeepReadonly, Ref, ShallowRef, UnwrapNestedRefs } from "vue";
 import { computed, getCurrentScope, isRef, onScopeDispose, ref, shallowRef, watch } from "vue";
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import type { NonGetHTTPMethod } from "../api/api";
+import type { MaybeExtractPathParamsOrWiden, QueryParamsHint } from "../api/internal/path";
+import { isReadableAtom } from "../util/nanostores";
+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 type { MaybeExtractPathParamsOrWiden, QueryParamsHint } from "../api/internal/path";
-import type { InferOr } from "../util/types-util";
 
 export type FragnoVueHook<
   _TMethod extends "GET",
@@ -46,6 +53,21 @@ export type FragnoVueMutator<
   data: Ref<InferOr<TOutputSchema, undefined>>;
 };
 
+/**
+ * Type helper that wraps any Store fields of the object into reactive Vue refs.
+ */
+type FragnoVueStoreRef<T extends Store> = DeepReadonly<UnwrapNestedRefs<ShallowRef<StoreValue<T>>>>;
+
+type FragnoVueStoreValue<T extends object> = T extends Store
+  ? FragnoVueStoreRef<T>
+  : {
+      [K in keyof T]: T[K] extends Store ? FragnoVueStoreRef<T[K]> : T[K];
+    };
+
+export type FragnoVueStore<T extends object, TArgs extends unknown[] = []> = (
+  ...args: TArgs
+) => FragnoVueStoreValue<T>;
+
 /**
  * Converts a Vue Ref to a NanoStore Atom.
  *
@@ -181,6 +203,48 @@ function createVueMutator<
   };
 }
 
+function unwrapVueStoreValue<T extends object>(value: T): FragnoVueStoreValue<T> {
+  if (isReadableAtom(value)) {
+    return useStore(value as Store) as FragnoVueStoreValue<T>;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result: any = {};
+
+  for (const key in value) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      continue;
+    }
+
+    const fieldValue = value[key];
+    if (isReadableAtom(fieldValue)) {
+      result[key] = useStore(fieldValue);
+    } else {
+      result[key] = fieldValue;
+    }
+  }
+
+  return result as FragnoVueStoreValue<T>;
+}
+
+// Helper function to create a Vue composable from a store
+function createVueStore<const T extends object, const TArgs extends unknown[]>(
+  hook: FragnoStoreData<T, TArgs>,
+): FragnoVueStore<T, TArgs> {
+  return ((...args: TArgs) => {
+    const value = "factory" in hook ? hook.factory(...args) : hook.obj;
+    const disposer = value[Symbol.dispose as keyof typeof value];
+
+    if (typeof disposer === "function" && getCurrentScope()) {
+      onScopeDispose(() => {
+        disposer.call(value);
+      });
+    }
+
+    return unwrapVueStoreValue(value);
+  }) as FragnoVueStore<T, TArgs>;
+}
+
 export function useFragno<T extends Record<string, unknown>>(
   clientObj: T,
 ): {
@@ -201,7 +265,11 @@ export function useFragno<T extends Record<string, unknown>>(
           infer TQueryParameters
         >
       ? FragnoVueMutator<M, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>
-      : T[K];
+      : T[K] extends FragnoStoreObjectData<infer TStoreObj>
+        ? FragnoVueStore<TStoreObj, []>
+        : T[K] extends FragnoStoreFactoryData<infer TStoreObj, infer TStoreArgs>
+          ? FragnoVueStore<TStoreObj, TStoreArgs>
+          : T[K];
 } {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const result = {} as any;
@@ -216,6 +284,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/id.ts

@@ -0,0 +1 @@
+export { createId, init } from "./internal/cuid";

package/src/internal/cuid.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createId, init } from "./cuid";
+
+const idPattern = /^[a-z][0-9a-z]*$/;
+
+const createSeededRandom = (seed: number) => {
+  let state = seed >>> 0;
+
+  return () => {
+    state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+    return state / 4294967296;
+  };
+};
+
+const createCounter = (start = 0) => {
+  let value = start;
+  return () => value++;
+};
+
+describe("cuid", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("creates ids with the default format", () => {
+    const id = createId();
+
+    expect(id).toHaveLength(24);
+    expect(id).toMatch(idPattern);
+  });
+
+  it("defers default state initialization until the first generated id", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const random = vi.fn(() => 0.5);
+
+    const generator = init({ random });
+
+    expect(random).not.toHaveBeenCalled();
+
+    generator();
+
+    expect(random).toHaveBeenCalled();
+  });
+
+  it("uses web-standard crypto randomness by default", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const mathRandomSpy = vi.spyOn(Math, "random");
+    const getRandomValuesSpy = vi.spyOn(globalThis.crypto, "getRandomValues");
+
+    const generator = init();
+    const ids = Array.from({ length: 10 }, () => generator());
+
+    expect(ids[0]).toHaveLength(24);
+    expect(ids[0]).toMatch(idPattern);
+    expect(mathRandomSpy).not.toHaveBeenCalled();
+    expect(getRandomValuesSpy).toHaveBeenCalled();
+  });
+
+  it("supports exact custom lengths including very short ids", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    for (const length of [1, 2, 8, 24, 32]) {
+      const id = init({
+        length,
+        random: createSeededRandom(123),
+        counter: createCounter(7),
+        fingerprint: "fingerprint",
+      })();
+
+      expect(id).toHaveLength(length);
+      expect(id).toMatch(idPattern);
+    }
+  });
+
+  it("creates deterministic sequences for the same configuration", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const first = init({
+      random: createSeededRandom(123),
+      counter: createCounter(10),
+      fingerprint: "fingerprint",
+    });
+    const second = init({
+      random: createSeededRandom(123),
+      counter: createCounter(10),
+      fingerprint: "fingerprint",
+    });
+
+    const firstIds = [first(), first(), first()];
+    const secondIds = [second(), second(), second()];
+
+    expect(firstIds).toEqual(secondIds);
+    expect(firstIds).toMatchInlineSnapshot(`
+      [
+        "h1bh5y4k2htp1bh5y4k2htp1",
+        "p1zxk77n8dqx1zxk77n8dqx1",
+        "u576un0v3is576un0v3is576",
+      ]
+    `);
+  });
+
+  it("changes the output when the fingerprint changes", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const withFirstFingerprint = init({
+      random: createSeededRandom(123),
+      counter: createCounter(10),
+      fingerprint: "fingerprint-a",
+    });
+    const withSecondFingerprint = init({
+      random: createSeededRandom(123),
+      counter: createCounter(10),
+      fingerprint: "fingerprint-b",
+    });
+
+    expect(withFirstFingerprint()).not.toBe(withSecondFingerprint());
+  });
+
+  it("remains collision-free across many ids even when time and random are fixed", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const generator = init({
+      random: () => 0,
+      counter: createCounter(0),
+      fingerprint: "fingerprint",
+    });
+
+    const ids = Array.from({ length: 1000 }, () => generator());
+
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(ids.every((id) => id.length === 24 && idPattern.test(id))).toBe(true);
+  });
+
+  it("uses the configured random source for the leading character", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const leadingA = init({
+      length: 8,
+      random: () => 0,
+      counter: createCounter(0),
+      fingerprint: "fingerprint",
+    })();
+    const leadingZ = init({
+      length: 8,
+      random: () => 0.999999,
+      counter: createCounter(0),
+      fingerprint: "fingerprint",
+    })();
+
+    expect(leadingA[0]).toBe("a");
+    expect(leadingZ[0]).toBe("z");
+  });
+});