@fragno-dev/core 0.0.6 → 0.1.0

package/src/api/{fragment.ts → fragment-instantiation.ts}

@@ -7,7 +7,6 @@ import { RequestInputContext } from "./request-input-context";
 import type { ExtractPathParams } from "./internal/path";
 import { RequestOutputContext } from "./request-output-context";
 import {
-  type EmptyObject,
   type AnyFragnoRouteConfig,
   type AnyRouteOrFactory,
   type FlattenRouteFactories,
@@ -18,6 +17,7 @@ import {
   RequestMiddlewareOutputContext,
   type FragnoMiddlewareCallback,
 } from "./request-middleware";
+import type { FragmentDefinition } from "./fragment-builder";
 
 export interface FragnoPublicConfig {
   mountRoute?: string;
@@ -37,6 +37,16 @@ type ReactRouterHandlers = {
   action: (args: { request: Request }) => Promise<Response>;
 };
 
+type SolidStartHandlers = {
+  GET: (args: { request: Request }) => Promise<Response>;
+  POST: (args: { request: Request }) => Promise<Response>;
+  PUT: (args: { request: Request }) => Promise<Response>;
+  DELETE: (args: { request: Request }) => Promise<Response>;
+  PATCH: (args: { request: Request }) => Promise<Response>;
+  HEAD: (args: { request: Request }) => Promise<Response>;
+  OPTIONS: (args: { request: Request }) => Promise<Response>;
+};
+
 type StandardHandlers = {
   GET: (req: Request) => Promise<Response>;
   POST: (req: Request) => Promise<Response>;
@@ -52,24 +62,32 @@ type HandlersByFramework = {
   "react-router": ReactRouterHandlers;
   "next-js": StandardHandlers;
   "svelte-kit": StandardHandlers;
+  "solid-start": SolidStartHandlers;
 };
 
+// Not actually a symbol, since we might be dealing with multiple instances of this code.
+export const instantiatedFragmentFakeSymbol = "$fragno-instantiated-fragment" as const;
+
 type FullstackFrameworks = keyof HandlersByFramework;
 
 export interface FragnoInstantiatedFragment<
   TRoutes extends readonly AnyFragnoRouteConfig[] = [],
-  TDeps = EmptyObject,
+  TDeps = {},
   TServices extends Record<string, unknown> = Record<string, unknown>,
+  TAdditionalContext extends Record<string, unknown> = {},
 > {
+  [instantiatedFragmentFakeSymbol]: typeof instantiatedFragmentFakeSymbol;
+
   config: FragnoFragmentSharedConfig<TRoutes>;
   deps: TDeps;
   services: TServices;
+  additionalContext?: TAdditionalContext;
   handlersFor: <T extends FullstackFrameworks>(framework: T) => HandlersByFramework[T];
   handler: (req: Request) => Promise<Response>;
   mountRoute: string;
   withMiddleware: (
     handler: FragnoMiddlewareCallback<TRoutes, TDeps, TServices>,
-  ) => FragnoInstantiatedFragment<TRoutes, TDeps, TServices>;
+  ) => FragnoInstantiatedFragment<TRoutes, TDeps, TServices, TAdditionalContext>;
 }
 
 export interface FragnoFragmentSharedConfig<
@@ -90,81 +108,38 @@ export type AnyFragnoFragmentSharedConfig = FragnoFragmentSharedConfig<
   readonly AnyFragnoRouteConfig[]
 >;
 
-interface FragmentDefinition<
-  TConfig,
-  TDeps = EmptyObject,
-  TServices extends Record<string, unknown> = EmptyObject,
-> {
-  name: string;
-  dependencies?: (config: TConfig) => TDeps;
-  services?: (config: TConfig, deps: TDeps) => TServices;
-}
-
-export class FragmentBuilder<
-  TConfig,
-  TDeps = EmptyObject,
-  TServices extends Record<string, unknown> = EmptyObject,
-> {
-  #definition: FragmentDefinition<TConfig, TDeps, TServices>;
-
-  constructor(definition: FragmentDefinition<TConfig, TDeps, TServices>) {
-    this.#definition = definition;
-  }
-
-  get definition() {
-    return this.#definition;
-  }
-
-  withDependencies<TNewDeps>(
-    fn: (config: TConfig) => TNewDeps,
-  ): FragmentBuilder<TConfig, TNewDeps, TServices> {
-    return new FragmentBuilder<TConfig, TNewDeps, TServices>({
-      ...this.#definition,
-      dependencies: fn,
-    } as FragmentDefinition<TConfig, TNewDeps, TServices>);
-  }
-
-  withServices<TNewServices extends Record<string, unknown>>(
-    fn: (config: TConfig, deps: TDeps) => TNewServices,
-  ): FragmentBuilder<TConfig, TDeps, TNewServices> {
-    return new FragmentBuilder<TConfig, TDeps, TNewServices>({
-      ...this.#definition,
-      services: fn,
-    } as FragmentDefinition<TConfig, TDeps, TNewServices>);
-  }
-}
-
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export function defineFragment<TConfig = {}>(name: string): FragmentBuilder<TConfig> {
-  return new FragmentBuilder({
-    name,
-  });
-}
-
 export function createFragment<
-  TConfig,
-  TDeps,
-  TServices extends Record<string, unknown>,
+  const TConfig,
+  const TDeps,
+  const TServices extends Record<string, unknown>,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
+  const TAdditionalContext extends Record<string, unknown>,
+  const TOptions extends FragnoPublicConfig,
 >(
-  fragmentDefinition: FragmentBuilder<TConfig, TDeps, TServices>,
+  fragmentBuilder: {
+    definition: FragmentDefinition<TConfig, TDeps, TServices, TAdditionalContext>;
+    $requiredOptions: TOptions;
+  },
   config: TConfig,
   routesOrFactories: TRoutesOrFactories,
-  fragnoConfig: FragnoPublicConfig = {},
-): FragnoInstantiatedFragment<FlattenRouteFactories<TRoutesOrFactories>, TDeps, TServices> {
-  const definition = fragmentDefinition.definition;
+  options: TOptions,
+): FragnoInstantiatedFragment<
+  FlattenRouteFactories<TRoutesOrFactories>,
+  TDeps,
+  TServices,
+  TAdditionalContext
+> {
+  const definition = fragmentBuilder.definition;
 
-  const dependencies = definition.dependencies ? definition.dependencies(config) : ({} as TDeps);
-  const services = definition.services
-    ? definition.services(config, dependencies)
-    : ({} as TServices);
+  const dependencies = definition.dependencies?.(config, options) ?? ({} as TDeps);
+  const services = definition.services?.(config, options, dependencies) ?? ({} as TServices);
 
   const context = { config, deps: dependencies, services };
   const routes = resolveRouteFactories(context, routesOrFactories);
 
   const mountRoute = getMountRoute({
     name: definition.name,
-    mountRoute: fragnoConfig.mountRoute,
+    mountRoute: options.mountRoute,
   });
 
   const router =
@@ -190,8 +165,10 @@ export function createFragment<
   const fragment: FragnoInstantiatedFragment<
     FlattenRouteFactories<TRoutesOrFactories>,
     TDeps,
-    TServices
+    TServices,
+    TAdditionalContext & TOptions
   > = {
+    [instantiatedFragmentFakeSymbol]: instantiatedFragmentFakeSymbol,
     mountRoute,
     config: {
       name: definition.name,
@@ -199,6 +176,10 @@ export function createFragment<
     },
     services,
     deps: dependencies,
+    additionalContext: {
+      ...definition.additionalContext,
+      ...options,
+    } as TAdditionalContext & TOptions,
     withMiddleware: (handler) => {
       if (middlewareHandler) {
         throw new Error("Middleware already set");
@@ -210,6 +191,14 @@ export function createFragment<
     },
     handlersFor: <T extends FullstackFrameworks>(framework: T): HandlersByFramework[T] => {
       const handler = fragment.handler;
+
+      // LLMs hallucinate these values sometimes, solution isn't obvious so we throw this error
+      // @ts-expect-error TS2367
+      if (framework === "h3" || framework === "nuxt") {
+        throw new Error(`To get handlers for h3, use the 'fromWebHandler' utility function:
+          import { fromWebHandler } from "h3";
+          export default fromWebHandler(myFragment().handler);`);
+      }
       const allHandlers = {
         astro: { ALL: handler },
         "react-router": {
@@ -234,6 +223,15 @@ export function createFragment<
           HEAD: handler,
           OPTIONS: handler,
         },
+        "solid-start": {
+          GET: ({ request }: { request: Request }) => handler(request),
+          POST: ({ request }: { request: Request }) => handler(request),
+          PUT: ({ request }: { request: Request }) => handler(request),
+          DELETE: ({ request }: { request: Request }) => handler(request),
+          PATCH: ({ request }: { request: Request }) => handler(request),
+          HEAD: ({ request }: { request: Request }) => handler(request),
+          OPTIONS: ({ request }: { request: Request }) => handler(request),
+        },
       } satisfies HandlersByFramework;
 
       return allHandlers[framework];

package/src/api/fragment.test.ts

@@ -1,5 +1,6 @@
 import { test, expect, describe, expectTypeOf } from "vitest";
-import { defineFragment, createFragment, type FragmentBuilder } from "./fragment";
+import { defineFragment, type FragmentBuilder } from "./fragment-builder";
+import { createFragment } from "./fragment-instantiation";
 import { defineRoute, defineRoutes, type RouteFactory, resolveRouteFactories } from "./route";
 import { z } from "zod";
 import type { InferOr } from "../util/types-util";
@@ -25,6 +26,7 @@ describe("new-fragment API", () => {
             debug: boolean;
           },
           Empty,
+          Empty,
           Empty
         >
       >();
@@ -35,8 +37,8 @@ describe("new-fragment API", () => {
         apiKey: "test-key",
       };
 
-      const _fragment = defineFragment<typeof _config>("test").withDependencies((cfg) => {
-        expectTypeOf(cfg).toEqualTypeOf<typeof _config>();
+      const _fragment = defineFragment<typeof _config>("test").withDependencies(({ config }) => {
+        expectTypeOf(config).toEqualTypeOf<typeof _config>();
         return {
           httpClient: { fetch: () => Promise.resolve(new Response()) },
           logger: { log: (msg: string) => console.log(msg) },
@@ -50,6 +52,7 @@ describe("new-fragment API", () => {
             httpClient: { fetch: () => Promise<Response> };
             logger: { log: (msg: string) => void };
           },
+          Empty,
           Empty
         >
       >();
@@ -62,16 +65,16 @@ describe("new-fragment API", () => {
       };
 
       const _fragment = defineFragment<typeof _config>("test")
-        .withDependencies((cfg) => {
-          expectTypeOf(cfg).toEqualTypeOf<{
+        .withDependencies(({ config }) => {
+          expectTypeOf(config).toEqualTypeOf<{
             apiKey: string;
             baseUrl: string;
           }>();
 
-          return { httpClient: { baseUrl: cfg.baseUrl } };
+          return { httpClient: { baseUrl: config.baseUrl } };
         })
-        .withServices((cfg, deps) => {
-          expectTypeOf(cfg).toEqualTypeOf<typeof _config>();
+        .withServices(({ config, deps }) => {
+          expectTypeOf(config).toEqualTypeOf<typeof _config>();
           expectTypeOf(deps).toEqualTypeOf<{ httpClient: { baseUrl: string } }>();
 
           return {
@@ -97,7 +100,8 @@ describe("new-fragment API", () => {
               get: (key: string) => string;
               set: (key: string, value: string) => void;
             };
-          }
+          },
+          Empty
         >
       >();
     });
@@ -155,13 +159,15 @@ describe("new-fragment API", () => {
       const _config = { test: true };
 
       const lib1 = defineFragment<typeof _config>("test");
-      expectTypeOf(lib1).toEqualTypeOf<FragmentBuilder<typeof _config, Empty, Empty>>();
+      expectTypeOf(lib1).toEqualTypeOf<FragmentBuilder<typeof _config, Empty, Empty, Empty>>();
 
       const lib2 = lib1.withDependencies(() => ({ dep1: "value1" }));
-      expectTypeOf(lib2).toEqualTypeOf<FragmentBuilder<typeof _config, { dep1: string }, Empty>>();
+      expectTypeOf(lib2).toEqualTypeOf<
+        FragmentBuilder<typeof _config, { dep1: string }, Empty, Empty>
+      >();
       const lib3 = lib2.withServices(() => ({ service1: "value1" }));
       expectTypeOf(lib3).toEqualTypeOf<
-        FragmentBuilder<typeof _config, { dep1: string }, { service1: string }>
+        FragmentBuilder<typeof _config, { dep1: string }, { service1: string }, Empty>
       >();
 
       expect(lib1).not.toBe(lib2);
@@ -173,10 +179,10 @@ describe("new-fragment API", () => {
       const _config = { apiKey: "test" };
 
       const fragment = defineFragment<typeof _config>("my-lib")
-        .withDependencies((_cfg) => ({
-          client: `Client for ${_cfg.apiKey}`,
+        .withDependencies(({ config }) => ({
+          client: `Client for ${config.apiKey}`,
         }))
-        .withServices((_cfg, deps) => ({
+        .withServices(({ deps }) => ({
           service: `Service using ${deps.client}`,
         }));
 
@@ -211,7 +217,7 @@ describe("new-fragment API", () => {
       ]);
 
       const fragmentDef = defineFragment("greeting")
-        .withDependencies((_config) => ({
+        .withDependencies(() => ({
           formatter: (s: string) => s.toUpperCase(),
         }))
         .withServices(() => ({
@@ -506,4 +512,26 @@ describe("new-fragment API", () => {
       expectTypeOf(routes[1].path).toEqualTypeOf<"/status">();
     });
   });
+
+  describe("Database Integration", () => {
+    test("createFragment without database works without adapter", () => {
+      const fragmentDef = defineFragment("test").withDependencies(() => ({
+        service: { data: "test" },
+      }));
+
+      const fragment = createFragment(fragmentDef, {}, [], {});
+
+      expect(fragment.deps.service.data).toBe("test");
+    });
+
+    test("createFragment accepts options parameter", () => {
+      const fragmentDef = defineFragment("test").withDependencies(() => ({
+        service: { data: "test" },
+      }));
+
+      const fragment = createFragment(fragmentDef, {}, [], { mountRoute: "/custom" });
+
+      expect(fragment.mountRoute).toBe("/custom");
+    });
+  });
 });

package/src/api/request-middleware.test.ts

@@ -1,5 +1,6 @@
 import { test, expect, describe, expectTypeOf } from "vitest";
-import { defineFragment, createFragment } from "./fragment";
+import { defineFragment } from "./fragment-builder";
+import { createFragment } from "./fragment-instantiation";
 import { defineRoute } from "./route";
 import { z } from "zod";
 import { FragnoApiValidationError } from "./error";
@@ -45,7 +46,7 @@ describe("Request Middleware", () => {
     expect(unauthorizedRes.status).toBe(401);
     const unauthorizedBody = await unauthorizedRes.json();
     expect(unauthorizedBody).toEqual({
-      error: "Unauthorized",
+      message: "Unauthorized",
       code: "UNAUTHORIZED",
     });
 
@@ -134,7 +135,7 @@ describe("Request Middleware", () => {
     expect(res.status).toBe(403);
 
     expect(await res.json()).toEqual({
-      error: "Creating users has been disabled.",
+      message: "Creating users has been disabled.",
       code: "CREATE_USERS_DISABLED",
     });
 
@@ -273,7 +274,7 @@ describe("Request Middleware", () => {
       }),
     ] as const;
 
-    const instance = createFragment(fragment, config, routes);
+    const instance = createFragment(fragment, config, routes, {});
 
     const withMiddleware = instance.withMiddleware(async () => {
       return undefined;
@@ -439,7 +440,7 @@ describe("Request Middleware", () => {
 
     const body = await res.json();
     expect(body).toEqual({
-      error: "Request validation failed in middleware",
+      message: "Request validation failed in middleware",
       code: "MIDDLEWARE_VALIDATION_ERROR",
     });
   });

package/src/api/request-output-context.ts

@@ -51,16 +51,16 @@ export abstract class OutputContext<const TOutput, const TErrorCode extends stri
     headers?: HeadersInit,
   ): Response {
     if (typeof initOrStatus === "undefined") {
-      return Response.json({ error: message, code }, { status: 500, headers });
+      return Response.json({ message: message, code }, { status: 500, headers });
     }
 
     if (typeof initOrStatus === "number") {
-      return Response.json({ error: message, code }, { status: initOrStatus, headers });
+      return Response.json({ message: message, code }, { status: initOrStatus, headers });
     }
 
     const mergedHeaders = mergeHeaders(initOrStatus.headers, headers);
     return Response.json(
-      { error: message, code },
+      { message: message, code },
       { status: initOrStatus.status, headers: mergedHeaders },
     );
   }

package/src/api/route.ts

@@ -125,14 +125,7 @@ export function defineRoute<
   return config;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export type EmptyObject = {}; //Record<string, never>;
-
-export function defineRoutes<
-  TConfig = EmptyObject,
-  TDeps = EmptyObject,
-  TServices = EmptyObject,
->() {
+export function defineRoutes<TConfig = {}, TDeps = {}, TServices = {}>() {
   return {
     create: <
       const TRoutes extends readonly FragnoRouteConfig<

package/src/client/client-builder.test.ts

@@ -2,8 +2,8 @@ import { test, expect, expectTypeOf, describe } from "vitest";
 import { z } from "zod";
 import { createClientBuilder } from "./client";
 import { addRoute } from "../api/api";
-import { defineFragment } from "../api/fragment";
-import type { FragnoPublicClientConfig } from "../api/fragment";
+import { defineFragment } from "../api/fragment-builder";
+import type { FragnoPublicClientConfig } from "../api/fragment-instantiation";
 
 // Test route configurations
 const testFragment = defineFragment("test-fragment");

package/src/client/client-error.test.ts

@@ -1,6 +1,7 @@
 import { test, expect, describe } from "vitest";
-import { FragnoClientApiError } from "./client-error";
+import { FragnoClientApiError, FragnoClientUnknownApiError } from "./client-error";
 import { FragnoApiError } from "../api/error";
+import { RequestOutputContext } from "../api/request-output-context";
 
 describe("Error Conversion", () => {
   test("should convert API error to client error", async () => {
@@ -12,4 +13,19 @@ describe("Error Conversion", () => {
     expect(clientError.code).toBe("API_ERROR");
     expect(clientError.status).toBe(500);
   });
+
+  test("error() should never result in an unknown error", async () => {
+    const ctx = new RequestOutputContext();
+    const response = ctx.error({ message: "test", code: "MY_TEST_ERROR" }, { status: 400 });
+
+    expect(response).toBeInstanceOf(Response);
+    expect(response.status).toBe(400);
+
+    const clientError = await FragnoClientApiError.fromResponse(response);
+    expect(clientError).toBeInstanceOf(FragnoClientApiError);
+    expect(clientError).not.toBeInstanceOf(FragnoClientUnknownApiError);
+    expect(clientError.message).toBe("test");
+    expect(clientError.code).toBe("MY_TEST_ERROR");
+    expect(clientError.status).toBe(400);
+  });
 });

package/src/client/client.ssr.test.ts

@@ -10,7 +10,7 @@ import { describe, expect, test } from "vitest";
 import { type FragnoPublicClientConfig } from "../mod";
 import { createClientBuilder } from "./client";
 import { defineRoute } from "../api/route";
-import { defineFragment } from "../api/fragment";
+import { defineFragment } from "../api/fragment-builder";
 import { z } from "zod";
 import { createAsyncIteratorFromCallback, waitForAsyncIterator } from "../util/async";
 

package/src/client/client.svelte.test.ts

@@ -3,7 +3,7 @@ import { type FragnoPublicClientConfig } from "../mod";
 import { createClientBuilder } from "./client";
 import { render } from "@testing-library/svelte";
 import { defineRoute } from "../api/route";
-import { defineFragment } from "../api/fragment";
+import { defineFragment } from "../api/fragment-builder";
 import { z } from "zod";
 import { readableToAtom, useFragno } from "./client.svelte";
 import { writable, readable, get, derived } from "svelte/store";

package/src/client/client.test.ts

@@ -6,7 +6,7 @@ import { useFragno } from "./vanilla";
 import { createAsyncIteratorFromCallback, waitForAsyncIterator } from "../util/async";
 import type { FragnoPublicClientConfig } from "../mod";
 import { atom, computed, effect } from "nanostores";
-import { defineFragment } from "../api/fragment";
+import { defineFragment } from "../api/fragment-builder";
 import { RequestOutputContext } from "../api/request-output-context";
 import { FragnoClientUnknownApiError } from "./client-error";
 

package/src/client/client.ts

@@ -12,7 +12,10 @@ import {
 import { getMountRoute } from "../api/internal/route";
 import { RequestInputContext } from "../api/request-input-context";
 import { RequestOutputContext } from "../api/request-output-context";
-import type { FragnoFragmentSharedConfig, FragnoPublicClientConfig } from "../api/fragment";
+import type {
+  FragnoFragmentSharedConfig,
+  FragnoPublicClientConfig,
+} from "../api/fragment-instantiation";
 import { FragnoClientApiError, FragnoClientError, FragnoClientFetchError } from "./client-error";
 import type { InferOr } from "../util/types-util";
 import { parseContentType } from "../util/content-type";
@@ -22,7 +25,7 @@ import {
 } from "./internal/ndjson-streaming";
 import { addStore, getInitialData, SSR_ENABLED } from "../util/ssr";
 import { unwrapObject } from "../util/nanostores";
-import type { FragmentBuilder } from "../api/fragment";
+import type { FragmentBuilder } from "../api/fragment-builder";
 import {
   type AnyRouteOrFactory,
   type FlattenRouteFactories,

package/src/client/react.test.ts

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { createClientBuilder } from "./client";
 import { useFragno, useStore, type FragnoReactStore } from "./react";
 import { defineRoute } from "../api/route";
-import { defineFragment } from "../api/fragment";
+import { defineFragment } from "../api/fragment-builder";
 import type { FragnoPublicClientConfig } from "../mod";
 import { FragnoClientFetchNetworkError, type FragnoClientError } from "./client-error";
 import { RequestOutputContext } from "../api/request-output-context";