@fragno-dev/core 0.1.11 → 0.2.2

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

package/src/mod-client.ts

@@ -35,7 +35,7 @@ export function defineFragment(_name: string) {
     name: _name,
   };
 
-  const stub = {
+  const stubMethods = {
     withDependencies: () => stub,
     providesBaseService: () => stub,
     providesService: () => stub,
@@ -45,10 +45,25 @@ 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())
+  const stub: object = new Proxy(stubMethods, {
+    get(target, prop) {
+      if (prop in target) {
+        return target[prop as keyof typeof target];
+      }
+      // Return a function that returns the stub for method chaining
+      return () => stub;
+    },
+  });
+
   return stub;
 }
 
@@ -58,7 +73,7 @@ export { FragmentDefinitionBuilder } from "./api/fragment-definition-builder";
 // Stub implementation for instantiate
 // This is stripped by unplugin-fragno in browser builds
 export function instantiate(_definition: unknown) {
-  const fragmentStub: IFragnoInstantiatedFragment = {
+  const fragmentStubMethods = {
     [instantiatedFragmentFakeSymbol]: instantiatedFragmentFakeSymbol,
     name: "",
     routes: [],
@@ -68,21 +83,32 @@ export function instantiate(_definition: unknown) {
       return {
         deps: {},
         options: {},
-        linkedFragments: {},
       };
     },
-    withMiddleware: () => {
-      // throw new Error("withMiddleware is not supported in browser builds");
-      return fragmentStub;
-    },
+    withMiddleware: () => fragmentStub,
     inContext: <T>(callback: () => T) => callback(),
+    callServices: async (_serviceCalls: () => unknown) => [],
     handlersFor: () => ({}),
     handler: async () => new Response(),
     callRoute: async () => ({ ok: true, data: undefined, error: undefined }),
     callRouteRaw: async () => new Response(),
   };
 
-  const builderStub: IFragmentInstantiationBuilder = {
+  // Wrap with Proxy to handle any additional methods
+  const fragmentStub: IFragnoInstantiatedFragment = new Proxy(
+    fragmentStubMethods as IFragnoInstantiatedFragment,
+    {
+      get(target, prop) {
+        if (prop in target) {
+          return target[prop as keyof typeof target];
+        }
+        // Return a function that returns the stub for method chaining
+        return () => fragmentStub;
+      },
+    },
+  );
+
+  const builderStubMethods = {
     withConfig: () => builderStub,
     withRoutes: () => builderStub,
     withOptions: () => builderStub,
@@ -94,6 +120,20 @@ export function instantiate(_definition: unknown) {
     options: undefined,
   };
 
+  // Wrap with Proxy to handle any additional methods
+  const builderStub: IFragmentInstantiationBuilder = new Proxy(
+    builderStubMethods as IFragmentInstantiationBuilder,
+    {
+      get(target, prop) {
+        if (prop in target) {
+          return target[prop as keyof typeof target];
+        }
+        // Return a function that returns the stub for method chaining
+        return () => builderStub;
+      },
+    },
+  );
+
   return builderStub;
 }
 
@@ -102,6 +142,12 @@ export function instantiate(_definition: unknown) {
 // ============================================================================
 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";
 
 // ============================================================================
@@ -25,14 +24,21 @@ export {
 // ============================================================================
 export type { FragnoPublicConfig } from "./api/shared-types";
 
+// ============================================================================
+// Runtime
+// ============================================================================
+export { defaultFragnoRuntime, type FragnoRuntime } from "./runtime";
+export { createId, init } from "./id";
+
 // ============================================================================
 // Route Definition
 // ============================================================================
 export {
   defineRoute,
   defineRoutes,
+  type AnyRouteOrFactory,
   type RouteFactory,
   type RouteFactoryContext,
 } from "./api/route";
 
-export { type FragnoRouteConfig, type RequestThisContext } from "./api/api";
+export { type FragnoRouteConfig, type RequestThisContext, type RouteContentType } from "./api/api";

package/src/runtime.ts

@@ -0,0 +1,48 @@
+import { createId } from "./id";
+
+export type FragnoRuntime = {
+  time: {
+    now: () => Date;
+  };
+  random: {
+    float: () => number;
+    uuid: () => string;
+    cuid: () => string;
+  };
+};
+
+const fallbackUuid = () => {
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = Math.floor(Math.random() * 256);
+  }
+
+  // RFC 4122 variant + version 4
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
+  return [
+    hex.slice(0, 4).join(""),
+    hex.slice(4, 6).join(""),
+    hex.slice(6, 8).join(""),
+    hex.slice(8, 10).join(""),
+    hex.slice(10, 16).join(""),
+  ].join("-");
+};
+
+const defaultUuid = () => {
+  const cryptoApi = globalThis.crypto;
+  return cryptoApi?.randomUUID ? cryptoApi.randomUUID() : fallbackUuid();
+};
+
+export const defaultFragnoRuntime: FragnoRuntime = {
+  time: {
+    now: () => new Date(),
+  },
+  random: {
+    float: () => Math.random(),
+    uuid: () => defaultUuid(),
+    cuid: () => createId(),
+  },
+};

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,13 +1,17 @@
 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,
   type ServiceConstructorFn,
 } from "../api/fragment-definition-builder";
-import { instantiateFragment, type FragnoInstantiatedFragment } from "../api/fragment-instantiator";
-import type { BoundServices } from "../api/bind-services";
+import {
+  instantiateFragment,
+  type FragnoInstantiatedFragment,
+  type RoutesWithInternal,
+} from "../api/fragment-instantiator";
+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";
@@ -200,6 +204,7 @@ export function createFragmentForTest<
   THandlerThisContext extends RequestThisContext,
   TRequestStorage,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
+  TInternalRoutes extends readonly AnyRouteOrFactory[] = readonly [],
 >(
   definition: FragmentDefinition<
     TConfig,
@@ -211,17 +216,19 @@ export function createFragmentForTest<
     TPrivateServices,
     TServiceThisContext,
     THandlerThisContext,
-    TRequestStorage
+    TRequestStorage,
+    TInternalRoutes
   >,
   routesOrFactories: TRoutesOrFactories,
   options: CreateFragmentForTestOptions<TConfig, TOptions, TServiceDependencies>,
 ): FragnoInstantiatedFragment<
-  FlattenRouteFactories<TRoutesOrFactories>,
+  RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TInternalRoutes>,
   TDeps,
   BoundServices<TBaseServices & TServices>,
   TServiceThisContext,
   THandlerThisContext,
-  TRequestStorage
+  TRequestStorage,
+  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",
@@ -22,6 +23,7 @@ export default defineConfig({
     "./src/integrations/react-ssr.ts",
     "./src/integrations/svelte-kit.ts",
     "./src/test/test.ts",
+    "./src/internal/trace-context.ts",
     "./src/internal/symbols.ts",
   ],
   dts: true,

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, {