@fragno-dev/core 0.0.1

package/src/client/vue.ts

@@ -0,0 +1,242 @@
+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 { NonGetHTTPMethod } from "../api/api";
+import {
+  isGetHook,
+  isMutatorHook,
+  type FragnoClientMutatorData,
+  type FragnoClientHookData,
+} 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",
+  TPath extends string,
+  TOutputSchema extends StandardSchemaV1,
+  TErrorCode extends string,
+  TQueryParameters extends string,
+> = (args?: {
+  path?: MaybeExtractPathParamsOrWiden<TPath, string | Ref<string> | ReadableAtom<string>>;
+  query?: QueryParamsHint<TQueryParameters, string | Ref<string> | ReadableAtom<string>>;
+}) => {
+  data: Ref<InferOr<TOutputSchema, undefined>>;
+  loading: Ref<boolean>;
+  error: Ref<FragnoClientError<TErrorCode[number]> | undefined>;
+};
+
+export type FragnoVueMutator<
+  _TMethod extends NonGetHTTPMethod,
+  TPath extends string,
+  TInputSchema extends StandardSchemaV1 | undefined,
+  TOutputSchema extends StandardSchemaV1 | undefined,
+  TErrorCode extends string,
+  TQueryParameters extends string,
+> = () => {
+  mutate: (args: {
+    body?: InferOr<TInputSchema, undefined>;
+    path?: MaybeExtractPathParamsOrWiden<TPath, string | Ref<string> | ReadableAtom<string>>;
+    query?: QueryParamsHint<TQueryParameters, string | Ref<string> | ReadableAtom<string>>;
+  }) => Promise<InferOr<TOutputSchema, undefined>>;
+  loading: Ref<boolean | undefined>;
+  error: Ref<FragnoClientError<TErrorCode[number]> | undefined>;
+  data: Ref<InferOr<TOutputSchema, undefined>>;
+};
+
+/**
+ * Converts a Vue Ref to a NanoStore Atom.
+ *
+ * This is used to convert Vue refs to atoms, so that we can use them in the store.
+ *
+ * @private
+ */
+export function refToAtom<T>(ref: Ref<T>): ReadableAtom<T> {
+  const a = atom(ref.value);
+
+  watch(ref, (newVal) => {
+    a.set(newVal);
+  });
+
+  // TODO: Do we need to unsubscribe, or is this handled by `onScopeDispose` below?
+
+  return a;
+}
+
+// Helper function to create a Vue composable from a GET hook
+// We want 1 store per hook, so on updates to params, we need to update the store instead of creating a new one.
+// Nanostores only works with atoms (or strings), so we need to convert vue refs to atoms.
+function createVueHook<
+  TMethod extends "GET",
+  TPath extends string,
+  TOutputSchema extends StandardSchemaV1,
+  TErrorCode extends string,
+  TQueryParameters extends string,
+>(
+  hook: FragnoClientHookData<TMethod, TPath, TOutputSchema, TErrorCode, TQueryParameters>,
+): FragnoVueHook<TMethod, TPath, TOutputSchema, TErrorCode, TQueryParameters> {
+  return ({ path, query } = {}) => {
+    const pathParams: Record<string, string | ReadableAtom<string>> = {};
+    const queryParams: Record<string, string | ReadableAtom<string>> = {};
+
+    for (const [key, value] of Object.entries(path ?? {})) {
+      const v = value as string | Ref<string> | ReadableAtom<string>;
+      pathParams[key] = isRef(v) ? refToAtom(v) : v;
+    }
+
+    for (const [key, value] of Object.entries(query ?? {})) {
+      // Dunno why the cast is necessary
+      const v = value as string | Ref<string> | ReadableAtom<string>;
+      queryParams[key] = isRef(v) ? (refToAtom(v) as ReadableAtom<string>) : v;
+    }
+
+    const store = hook.store({
+      path: pathParams as MaybeExtractPathParamsOrWiden<TPath, string | ReadableAtom<string>>,
+      query: queryParams,
+    });
+
+    const data = ref();
+    const loading = ref();
+    const error = ref();
+
+    const unsubscribe = store.subscribe((updatedStoreValue) => {
+      data.value = updatedStoreValue.data;
+      loading.value = updatedStoreValue.loading;
+      error.value = updatedStoreValue.error;
+    });
+
+    if (getCurrentScope()) {
+      onScopeDispose(() => {
+        unsubscribe();
+      });
+    }
+
+    return {
+      data,
+      loading,
+      error,
+    };
+  };
+}
+
+// Helper function to create a Vue mutator from a mutator hook
+function createVueMutator<
+  TMethod extends NonGetHTTPMethod,
+  TPath extends string,
+  TInputSchema extends StandardSchemaV1 | undefined,
+  TOutputSchema extends StandardSchemaV1 | undefined,
+  TErrorCode extends string,
+  TQueryParameters extends string,
+>(
+  hook: FragnoClientMutatorData<
+    TMethod,
+    TPath,
+    TInputSchema,
+    TOutputSchema,
+    TErrorCode,
+    TQueryParameters
+  >,
+): FragnoVueMutator<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters> {
+  return () => {
+    const store = useStore(hook.mutatorStore);
+
+    // Create a wrapped mutate function that handles Vue refs
+    const mutate = async (args: {
+      body?: InferOr<TInputSchema, undefined>;
+      path?: MaybeExtractPathParamsOrWiden<TPath, string | Ref<string> | ReadableAtom<string>>;
+      query?: QueryParamsHint<TQueryParameters, string | Ref<string> | ReadableAtom<string>>;
+    }) => {
+      const { body, path, query } = args;
+
+      const pathParams: Record<string, string | ReadableAtom<string>> = {};
+      const queryParams: Record<string, string | ReadableAtom<string>> = {};
+
+      for (const [key, value] of Object.entries(path ?? {})) {
+        const v = value as string | Ref<string> | ReadableAtom<string>;
+        pathParams[key] = isRef(v) ? v.value : v;
+      }
+
+      for (const [key, value] of Object.entries(query ?? {})) {
+        const v = value as string | Ref<string> | ReadableAtom<string>;
+        queryParams[key] = isRef(v) ? v.value : v;
+      }
+
+      // Call the store's mutate function with normalized params
+      return store.value.mutate({
+        body,
+        path: pathParams as MaybeExtractPathParamsOrWiden<TPath, string | ReadableAtom<string>>,
+        query: queryParams,
+      });
+    };
+
+    // Return the store-like object with Vue reactive refs
+    return {
+      mutate,
+      loading: computed(() => store.value.loading),
+      error: computed(() => store.value.error),
+      data: computed(() => store.value.data) as Ref<InferOr<TOutputSchema, undefined>>,
+    };
+  };
+}
+
+export function useFragno<T extends Record<string, unknown>>(
+  clientObj: T,
+): {
+  [K in keyof T]: T[K] extends FragnoClientHookData<
+    "GET",
+    infer TPath,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters
+  >
+    ? FragnoVueHook<"GET", TPath, TOutputSchema, TErrorCode, TQueryParameters>
+    : T[K] extends FragnoClientMutatorData<
+          infer M,
+          infer TPath,
+          infer TInputSchema,
+          infer TOutputSchema,
+          infer TErrorCode,
+          infer TQueryParameters
+        >
+      ? FragnoVueMutator<M, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>
+      : T[K];
+} {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result = {} as any;
+
+  for (const key in clientObj) {
+    if (!Object.prototype.hasOwnProperty.call(clientObj, key)) {
+      continue;
+    }
+
+    const hook = clientObj[key];
+    if (isGetHook(hook)) {
+      result[key] = createVueHook(hook);
+    } else if (isMutatorHook(hook)) {
+      result[key] = createVueMutator(hook);
+    } else {
+      // Pass through non-hook values unchanged
+      result[key] = hook;
+    }
+  }
+
+  return result;
+}
+
+export function useStore<SomeStore extends Store, Value extends StoreValue<SomeStore>>(
+  store: SomeStore,
+): DeepReadonly<UnwrapNestedRefs<ShallowRef<Value>>> {
+  const state = shallowRef();
+
+  const unsubscribe = store.subscribe((value) => {
+    state.value = value;
+  });
+
+  if (getCurrentScope()) {
+    onScopeDispose(unsubscribe);
+  }
+
+  return state;
+}

package/src/http/http-status.ts

@@ -0,0 +1,60 @@
+/**
+ * @module
+ * HTTP Status utility.
+ *
+ * Modified from honojs/hono
+ * Original source: https://github.com/honojs/hono/blob/0e3db674ad3f40be215a55a18062dd8e387ce525/src/utils/http-status.ts
+ * License: MIT
+ * Date obtained: August 28 2025
+ * Copyright (c) 2021-present Yusuke Wada and Hono contributors
+ *
+ */
+
+export type InfoStatusCode = 100 | 101 | 102 | 103;
+export type SuccessStatusCode = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226;
+export type DeprecatedStatusCode = 305 | 306;
+export type RedirectStatusCode = 300 | 301 | 302 | 303 | 304 | DeprecatedStatusCode | 307 | 308;
+export type ClientErrorStatusCode =
+  | 400
+  | 401
+  | 402
+  | 403
+  | 404
+  | 405
+  | 406
+  | 407
+  | 408
+  | 409
+  | 410
+  | 411
+  | 412
+  | 413
+  | 414
+  | 415
+  | 416
+  | 417
+  | 418
+  | 421
+  | 422
+  | 423
+  | 424
+  | 425
+  | 426
+  | 428
+  | 429
+  | 431
+  | 451;
+export type ServerErrorStatusCode = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511;
+
+/**
+ * If you want to use an unofficial status, use `UnofficialStatusCode`.
+ */
+export type StatusCode =
+  | InfoStatusCode
+  | SuccessStatusCode
+  | RedirectStatusCode
+  | ClientErrorStatusCode
+  | ServerErrorStatusCode;
+
+export type ContentlessStatusCode = 101 | 204 | 205 | 304;
+export type ContentfulStatusCode = Exclude<StatusCode, ContentlessStatusCode>;

package/src/integrations/astro.ts

@@ -0,0 +1,17 @@
+export interface AstroHandlers {
+  ALL: ({ request }: { request: Request }) => Promise<Response>;
+}
+
+/**
+ * Converts a Fragno fragment handler to an Astro API route handler
+ *
+ * @param fragment - The Fragno fragment instance
+ * @returns An Astro API route handler function
+ */
+export function toAstroHandler(handler: (req: Request) => Promise<Response>): AstroHandlers {
+  return {
+    ALL: async ({ request }) => {
+      return handler(request);
+    },
+  };
+}

package/src/integrations/next-js.ts

@@ -0,0 +1,31 @@
+export interface NextJsHandlers {
+  GET: (request: Request) => Promise<Response>;
+  POST: (request: Request) => Promise<Response>;
+  PUT: (request: Request) => Promise<Response>;
+  PATCH: (request: Request) => Promise<Response>;
+  DELETE: (request: Request) => Promise<Response>;
+}
+
+export function toNextJsHandler<T extends { handler: (req: Request) => Promise<Response> }>(
+  fragment: T,
+): NextJsHandlers;
+export function toNextJsHandler(handler: (req: Request) => Promise<Response>): NextJsHandlers;
+export function toNextJsHandler(
+  fragmentOrHandler:
+    | { handler: (req: Request) => Promise<Response> }
+    | ((req: Request) => Promise<Response>),
+): NextJsHandlers {
+  const handler = async (request: Request) => {
+    return "handler" in fragmentOrHandler
+      ? fragmentOrHandler.handler(request)
+      : fragmentOrHandler(request);
+  };
+
+  return {
+    GET: handler,
+    POST: handler,
+    PUT: handler,
+    PATCH: handler,
+    DELETE: handler,
+  };
+}

package/src/integrations/react-ssr.ts

@@ -0,0 +1,40 @@
+import { cleanStores, getFinalStoreValues } from "../util/ssr";
+
+/**
+ * Advice from https://pragmaticwebsecurity.com/articles/spasecurity/json-stringify-xss.html
+ * @param obj
+ * @returns
+ */
+function javascriptEscaped(obj: unknown) {
+  return JSON.stringify(obj).replace(/</g, "\\u003c");
+}
+
+/**
+ * This method should be called after a first render pass is finished.
+ * It gets all values from the stores and embeds them in a script tag in the HTML body.
+ *
+ * On the client side, this script tag is used to hydrate the stores.
+ * Be sure to also call finishServerLoad when the page is rendered, to reset the stores for the next request.
+ *
+ * @returns A string to be embedded in a script tag in the HTML body
+ */
+export async function startServerLoad(): Promise<string> {
+  const initialStoreValues = await getFinalStoreValues();
+
+  console.log("initialStoreValues", initialStoreValues);
+
+  return `window.__FRAGNO_INITIAL_DATA__ = ${javascriptEscaped(
+    Array.from(initialStoreValues.entries()),
+  )}`;
+}
+
+export async function initServerLoad() {
+  cleanStores();
+}
+
+/**
+ * Reset the stores for the next request.
+ */
+export async function finishServerLoad() {
+  cleanStores();
+}

package/src/integrations/svelte-kit.ts

@@ -0,0 +1,41 @@
+type MaybePromise<T> = T | Promise<T>;
+
+type SvelteKitRequestEvent = {
+  request: Request;
+};
+
+export type SvelteKitRequestHandler = (event: SvelteKitRequestEvent) => MaybePromise<Response>;
+
+export interface SvelteKitHandlers {
+  GET: SvelteKitRequestHandler;
+  POST: SvelteKitRequestHandler;
+  PUT: SvelteKitRequestHandler;
+  PATCH: SvelteKitRequestHandler;
+  DELETE: SvelteKitRequestHandler;
+  OPTIONS: SvelteKitRequestHandler;
+}
+
+export function toSvelteHandler<T extends { handler: (req: Request) => Promise<Response> }>(
+  fragment: T,
+): SvelteKitHandlers;
+export function toSvelteHandler(handler: (req: Request) => Promise<Response>): SvelteKitHandlers;
+export function toSvelteHandler(
+  fragmentOrHandler:
+    | { handler: (req: Request) => Promise<Response> }
+    | ((req: Request) => Promise<Response>),
+): SvelteKitHandlers {
+  const requestHandler: SvelteKitRequestHandler = async ({ request }) => {
+    return "handler" in fragmentOrHandler
+      ? fragmentOrHandler.handler(request)
+      : fragmentOrHandler(request);
+  };
+
+  return {
+    GET: requestHandler,
+    POST: requestHandler,
+    PUT: requestHandler,
+    PATCH: requestHandler,
+    DELETE: requestHandler,
+    OPTIONS: requestHandler,
+  };
+}

package/src/mod.ts

@@ -0,0 +1,20 @@
+export {
+  defineFragment,
+  createFragment,
+  FragmentBuilder,
+  type FragnoFragmentSharedConfig,
+  type FragnoPublicConfig,
+  type FragnoPublicClientConfig,
+  type FragnoInstantiatedFragment,
+} from "./api/fragment";
+
+export { type FragnoRouteConfig } from "./api/api";
+
+export {
+  defineRoute,
+  defineRoutes,
+  type RouteFactory,
+  type RouteFactoryContext,
+  type AnyRouteOrFactory,
+  type FlattenRouteFactories,
+} from "./api/route";

package/src/util/async.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "vitest";
+import { createAsyncIteratorFromCallback, waitForAsyncIterator } from "./async";
+
+describe("createAsyncIteratorFromCallback", () => {
+  test("yields values from callback", async () => {
+    let callback: ((value: string) => void) | null = null;
+    let unsubscribeCalled = false;
+
+    const subscribe = (cb: (value: string) => void) => {
+      callback = cb;
+      return () => {
+        unsubscribeCalled = true;
+      };
+    };
+
+    const iterator = createAsyncIteratorFromCallback(subscribe);
+
+    // Start consuming the iterator
+    const consumePromise = (async () => {
+      const values: string[] = [];
+      for await (const value of iterator) {
+        values.push(value);
+        if (values.length === 3) break;
+      }
+      return values;
+    })();
+
+    // Emit values
+    callback!("first");
+    callback!("second");
+    callback!("third");
+
+    const result = await consumePromise;
+    expect(result).toEqual(["first", "second", "third"]);
+    expect(unsubscribeCalled).toBe(true);
+  });
+
+  test("calls unsubscribe when iterator is terminated early", async () => {
+    let callback: ((value: string) => void) | null = null;
+    let unsubscribeCalled = false;
+
+    const subscribe = (cb: (value: string) => void) => {
+      callback = cb;
+      return () => {
+        unsubscribeCalled = true;
+      };
+    };
+
+    const iterator = createAsyncIteratorFromCallback(subscribe);
+
+    // Start consuming but break early
+    const consumePromise = (async () => {
+      const values: string[] = [];
+      for await (const value of iterator) {
+        values.push(value);
+        if (values.length === 2) break; // Break after 2 values
+      }
+      return values;
+    })();
+
+    // Emit 3 values
+    callback!("first");
+    callback!("second");
+    callback!("third");
+
+    const result = await consumePromise;
+    expect(result).toEqual(["first", "second"]);
+    expect(unsubscribeCalled).toBe(true);
+  });
+});
+
+describe("waitForAsyncIterator", () => {
+  test("actually times out", async () => {
+    const iterable = {
+      [Symbol.asyncIterator]: async function* () {
+        await new Promise((resolve) => setTimeout(resolve, 5000));
+        yield "test";
+      },
+    };
+
+    await expect(waitForAsyncIterator(iterable, () => false, { timeout: 1 })).rejects.toThrow(
+      "waitForAsyncIterator: Timeout after 1ms",
+    );
+  });
+});

package/src/util/async.ts

@@ -0,0 +1,96 @@
+type SubscribeFn<T> = (callback: (value: T) => void) => UnsubscribeFn | void;
+type UnsubscribeFn = () => void;
+
+/**
+ * Creates an async iterator from a subscribe function that follows the observable pattern.
+ *
+ * @template T The type of values produced by the store.
+ * @param subscribe A function that subscribes to store updates. It receives a callback to be
+ *          called on each update, and returns an unsubscribe function.
+ * @returns An async generator that yields store values as they are produced.
+ */
+export function createAsyncIteratorFromCallback<T>(
+  subscribe: SubscribeFn<T>,
+): AsyncGenerator<T, void, unknown> {
+  const queue: T[] = [];
+  let unsubscribe: UnsubscribeFn | null = null;
+  let resolveNext: ((value: IteratorResult<T>) => void) | null = null;
+
+  const unsubscribeFunc = subscribe((value) => {
+    if (resolveNext) {
+      // If there's a pending promise, resolve it immediately
+      resolveNext({ value, done: false });
+      resolveNext = null;
+    } else {
+      // Otherwise, queue the value
+      queue.push(value);
+    }
+  });
+
+  // Store unsubscribe function if one was returned
+  if (typeof unsubscribeFunc === "function") {
+    unsubscribe = unsubscribeFunc;
+  }
+
+  return (async function* () {
+    try {
+      while (true) {
+        if (queue.length > 0) {
+          // Yield queued values
+          yield queue.shift()!;
+        } else {
+          // Wait for the next value
+          yield await new Promise<T>((resolve) => {
+            resolveNext = (result) => {
+              if (!result.done) {
+                resolve(result.value);
+              }
+            };
+          });
+        }
+      }
+    } finally {
+      // Clean up subscription on iterator termination
+      if (unsubscribe) {
+        unsubscribe();
+      }
+    }
+  })();
+}
+
+/**
+ * Waits for an async iterator to yield a value that meets a condition.
+ *
+ * @template T The type of values produced by the iterator.
+ * @param iterable The async iterable to wait for.
+ * @param condition A function that checks if a value meets the condition.
+ * @param options Optional configuration options.
+ * @returns A promise that resolves to the first value that meets the condition.
+ */
+export async function waitForAsyncIterator<T>(
+  iterable: AsyncIterable<T>,
+  condition: (value: T) => boolean,
+  options: { timeout?: number } = {},
+): Promise<T> {
+  const { timeout = 1000 } = options;
+
+  // Create a timeout promise that rejects after the specified time
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(`waitForAsyncIterator: Timeout after ${timeout}ms`));
+    }, timeout);
+  });
+
+  // Create a promise that resolves when the condition is met
+  const iteratorPromise = (async () => {
+    for await (const value of iterable) {
+      if (condition(value)) {
+        return value;
+      }
+    }
+    throw new Error("waitForAsyncIterator: Iterator completed without meeting condition");
+  })();
+
+  // Race between the timeout and the iterator
+  return Promise.race([iteratorPromise, timeoutPromise]);
+}