@fragno-dev/core 0.2.0 → 0.2.2

package/src/client/vue.ts

@@ -1,8 +1,13 @@
-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,
@@ -10,11 +15,10 @@ import {
   type FragnoClientMutatorData,
   type FragnoClientHookData,
   type FragnoStoreData,
+  type FragnoStoreFactoryData,
+  type FragnoStoreObjectData,
 } 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";
 
 export type FragnoVueHook<
   _TMethod extends "GET",
@@ -50,14 +54,20 @@ export type FragnoVueMutator<
 };
 
 /**
- * Type helper that unwraps any Store fields of the object into StoreValues
+ * Type helper that wraps any Store fields of the object into reactive Vue refs.
  */
-export type FragnoVueStore<T extends object> = () => T extends Store<infer TStore>
-  ? StoreValue<TStore>
+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 ? StoreValue<T[K]> : T[K];
+      [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.
  *
@@ -193,31 +203,46 @@ 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>;
+function unwrapVueStoreValue<T extends object>(value: T): FragnoVueStoreValue<T> {
+  if (isReadableAtom(value)) {
+    return useStore(value as Store) as FragnoVueStoreValue<T>;
   }
 
-  return (() => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const result: any = {};
+  // 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;
-      }
+  for (const key in value) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      continue;
+    }
 
-      const value = hook.obj[key];
-      if (isReadableAtom(value)) {
-        result[key] = useStore(value).value;
-      } else {
-        result[key] = value;
-      }
+    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 result;
-  }) as FragnoVueStore<T>;
+    return unwrapVueStoreValue(value);
+  }) as FragnoVueStore<T, TArgs>;
 }
 
 export function useFragno<T extends Record<string, unknown>>(
@@ -240,9 +265,11 @@ export function useFragno<T extends Record<string, unknown>>(
           infer TQueryParameters
         >
       ? FragnoVueMutator<M, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>
-      : T[K] extends FragnoStoreData<infer TStoreObj>
-        ? FragnoVueStore<TStoreObj>
-        : 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;

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");
+  });
+});

package/src/internal/cuid.ts

@@ -0,0 +1,133 @@
+const defaultLength = 24;
+const bigLength = 32;
+const initialCountMax = 476782367;
+const randomPoolSize = 128;
+const uint32ToFloatScale = 1 / 4294967296;
+
+const alphabet = "abcdefghijklmnopqrstuvwxyz";
+const entropyAlphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
+
+const createCryptoRandom = (cryptoApi = globalThis.crypto) => {
+  if (!cryptoApi?.getRandomValues) {
+    throw new Error("Fragno cuid requires globalThis.crypto.getRandomValues()");
+  }
+
+  const values = new Uint32Array(randomPoolSize);
+  let offset = values.length;
+
+  return () => {
+    if (offset >= values.length) {
+      cryptoApi.getRandomValues(values);
+      offset = 0;
+    }
+
+    const value = values[offset]!;
+    offset += 1;
+    return value * uint32ToFloatScale;
+  };
+};
+
+const cryptoRandom = (() => {
+  let random: (() => number) | undefined;
+
+  return () => {
+    random ??= createCryptoRandom();
+    return random();
+  };
+})();
+
+const pickIndex = (random: () => number, length: number) => {
+  const value = random();
+
+  if (value <= 0) {
+    return 0;
+  }
+
+  if (value >= 1) {
+    return length - 1;
+  }
+
+  return Math.floor(value * length);
+};
+
+const createEntropy = (length = 4, random = cryptoRandom) => {
+  let entropy = "";
+
+  while (entropy.length < length) {
+    entropy += entropyAlphabet[pickIndex(random, entropyAlphabet.length)] ?? "0";
+  }
+
+  return entropy;
+};
+
+const hash53 = (input: string, seed = 0) => {
+  let h1 = 0xdeadbeef ^ seed;
+  let h2 = 0x41c6ce57 ^ seed;
+
+  for (let i = 0; i < input.length; i += 1) {
+    const code = input.charCodeAt(i);
+    h1 = Math.imul(h1 ^ code, 2654435761);
+    h2 = Math.imul(h2 ^ code, 1597334677);
+  }
+
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+};
+
+const hash = (input: string, length = bigLength) => {
+  let output = "";
+  let seed = 0;
+
+  while (output.length < length) {
+    output += hash53(`${seed}:${input}`, seed).toString(36);
+    seed += 1;
+  }
+
+  return output.slice(0, length);
+};
+
+const createFingerprint = ({
+  random = cryptoRandom,
+}: {
+  random?: () => number;
+} = {}) => createEntropy(bigLength, random);
+
+const createCounter = (count: number) => () => count++;
+
+export const init = ({
+  random = cryptoRandom,
+  counter,
+  length = defaultLength,
+  fingerprint,
+}: {
+  random?: () => number;
+  counter?: () => number;
+  length?: number;
+  fingerprint?: string;
+} = {}) => {
+  const normalizedLength = Math.max(1, Math.floor(length));
+  let resolvedCounter = counter;
+  let resolvedFingerprint = fingerprint;
+
+  return () => {
+    resolvedCounter ??= createCounter(pickIndex(random, initialCountMax));
+    resolvedFingerprint ??= createFingerprint({ random });
+
+    const firstLetter = alphabet[pickIndex(random, alphabet.length)] ?? "a";
+
+    if (normalizedLength === 1) {
+      return firstLetter;
+    }
+
+    const time = Date.now().toString(36);
+    const count = resolvedCounter().toString(36);
+    const salt = createEntropy(normalizedLength, random);
+    const body = hash(`${time}:${salt}:${count}:${resolvedFingerprint}`, normalizedLength - 1);
+    return `${firstLetter}${body}`;
+  };
+};
+
+// Safe to keep at module scope: init() defers all randomness until the first ID request.
+export const createId = init();

package/src/mod-client.ts

@@ -45,11 +45,12 @@ export function defineFragment(_name: string) {
     withRequestStorage: () => stub,
     withExternalRequestStorage: () => stub,
     withThisContext: () => stub,
-    withLinkedFragment: () => stub,
+    withInternalRoutes: () => stub,
     extend: () => stub,
     build: () => definitionStub,
     // From fragno-db
     provideHooks: () => stub,
+    withSyncCommands: () => stub,
   };
 
   // Wrap with Proxy to handle any additional methods (e.g. from extend())
@@ -82,11 +83,11 @@ export function instantiate(_definition: unknown) {
       return {
         deps: {},
         options: {},
-        linkedFragments: {},
       };
     },
     withMiddleware: () => fragmentStub,
     inContext: <T>(callback: () => T) => callback(),
+    callServices: async (_serviceCalls: () => unknown) => [],
     handlersFor: () => ({}),
     handler: async () => new Response(),
     callRoute: async () => ({ ok: true, data: undefined, error: undefined }),
@@ -145,6 +146,7 @@ export type { FragnoPublicConfig } from "./api/shared-types";
 // Runtime
 // ============================================================================
 export { defaultFragnoRuntime, type FragnoRuntime } from "./runtime";
+export { createId, init } from "./id";
 
 // ============================================================================
 // Route Definition

package/src/mod.ts

@@ -7,8 +7,6 @@ export {
   type FragmentDefinition,
   type ServiceContext,
   type ServiceConstructorFn,
-  type LinkedFragmentCallback,
-  type ExtractLinkedServices,
 } from "./api/fragment-definition-builder";
 
 export {
@@ -18,6 +16,7 @@ export {
   type AnyFragnoInstantiatedFragment,
   type BoundServices,
   type InstantiatedFragmentFromDefinition,
+  type FragnoRequestLifecycleContext,
 } from "./api/fragment-instantiator";
 
 // ============================================================================
@@ -29,6 +28,7 @@ export type { FragnoPublicConfig } from "./api/shared-types";
 // Runtime
 // ============================================================================
 export { defaultFragnoRuntime, type FragnoRuntime } from "./runtime";
+export { createId, init } from "./id";
 
 // ============================================================================
 // Route Definition
@@ -36,6 +36,7 @@ export { defaultFragnoRuntime, type FragnoRuntime } from "./runtime";
 export {
   defineRoute,
   defineRoutes,
+  type AnyRouteOrFactory,
   type RouteFactory,
   type RouteFactoryContext,
 } from "./api/route";

package/src/runtime.ts

@@ -1,4 +1,4 @@
-import { createId } from "@paralleldrive/cuid2";
+import { createId } from "./id";
 
 export type FragnoRuntime = {
   time: {

package/src/test/test.test.ts

@@ -1,8 +1,10 @@
 import { describe, it, expect } from "vitest";
-import { createFragmentForTest, withTestUtils } from "./test";
+
+import { z } from "zod";
+
 import { defineFragment } from "../api/fragment-definition-builder";
 import { defineRoutes } from "../api/route";
-import { z } from "zod";
+import { createFragmentForTest, withTestUtils } from "./test";
 
 describe("withTestUtils extension", () => {
   it("should expose deps via services.deps", () => {

package/src/test/test.ts

@@ -1,6 +1,5 @@
 import type { RequestThisContext } from "../api/api";
-import type { AnyRouteOrFactory, FlattenRouteFactories } from "../api/route";
-import type { FragnoPublicConfig } from "../api/shared-types";
+import type { BoundServices } from "../api/bind-services";
 import {
   FragmentDefinitionBuilder,
   type FragmentDefinition,
@@ -8,11 +7,11 @@ import {
 } from "../api/fragment-definition-builder";
 import {
   instantiateFragment,
-  type AnyFragnoInstantiatedFragment,
   type FragnoInstantiatedFragment,
   type RoutesWithInternal,
 } from "../api/fragment-instantiator";
-import type { BoundServices } from "../api/bind-services";
+import type { AnyRouteOrFactory, FlattenRouteFactories } from "../api/route";
+import type { FragnoPublicConfig } from "../api/shared-types";
 
 // Re-export for convenience
 export type { RouteHandlerInputOptions } from "../api/route-handler-input-options";
@@ -205,7 +204,7 @@ export function createFragmentForTest<
   THandlerThisContext extends RequestThisContext,
   TRequestStorage,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},
+  TInternalRoutes extends readonly AnyRouteOrFactory[] = readonly [],
 >(
   definition: FragmentDefinition<
     TConfig,
@@ -218,19 +217,18 @@ export function createFragmentForTest<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >,
   routesOrFactories: TRoutesOrFactories,
   options: CreateFragmentForTestOptions<TConfig, TOptions, TServiceDependencies>,
 ): FragnoInstantiatedFragment<
-  RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TLinkedFragments>,
+  RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TInternalRoutes>,
   TDeps,
   BoundServices<TBaseServices & TServices>,
   TServiceThisContext,
   THandlerThisContext,
   TRequestStorage,
-  TOptions,
-  TLinkedFragments
+  TOptions
 > {
   const { config, options: fragmentOptions = {} as TOptions, serviceImplementations } = options;
 

package/src/util/async.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "vitest";
+
 import { createAsyncIteratorFromCallback, waitForAsyncIterator } from "./async";
 
 describe("createAsyncIteratorFromCallback", () => {

package/src/util/content-type.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+
 import { parseContentType } from "./content-type";
 
 describe("parseContentType", () => {

package/src/util/nanostores.test.ts

@@ -1,7 +1,9 @@
 import { describe, test, expect } from "vitest";
-import { isReadableAtom } from "./nanostores";
+
 import { atom, map } from "nanostores";
 
+import { isReadableAtom } from "./nanostores";
+
 describe("nanostores", () => {
   test("isReadableAtom should return true for a readable atom", () => {
     const store = atom(0);

package/src/util/ssr.ts

@@ -1,4 +1,5 @@
 import { allTasks } from "nanostores";
+
 import type { FetcherStore } from "@nanostores/query";
 
 let stores: FetcherStore[] = [];

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "@fragno-private/typescript-config/tsconfig.base.json",
+  "extends": "@fragno-private/typescript-config/tsconfig.node.json",
   "compilerOptions": {
     "outDir": "./dist",
     "rootDir": ".",

package/tsdown.config.ts

@@ -12,6 +12,7 @@ export default defineConfig({
     "./src/api/request-context-storage.ts",
     "./src/request/request.ts",
     "./src/client/client.ts",
+    "./src/id.ts",
     "./src/client/vanilla.ts",
     "./src/client/client.svelte.ts",
     "./src/client/react.ts",

package/vitest.config.ts

@@ -1,7 +1,8 @@
+import { svelteTesting } from "@testing-library/svelte/vite";
 import { defineConfig, mergeConfig } from "vitest/config";
+
 import { baseConfig } from "@fragno-private/vitest-config";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { svelteTesting } from "@testing-library/svelte/vite";
 
 export default defineConfig(
   mergeConfig(baseConfig, {