@fragno-dev/core 0.0.7 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragno-dev/core",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "exports": {
     ".": {
       "bun": "./src/mod.ts",
@@ -14,6 +14,18 @@
       "types": "./dist/api/api.d.ts",
       "default": "./dist/api/api.js"
     },
+    "./api/fragment-builder": {
+      "bun": "./src/api/fragment-builder.ts",
+      "development": "./src/api/fragment-builder.ts",
+      "types": "./dist/api/fragment-builder.d.ts",
+      "default": "./dist/api/fragment-builder.js"
+    },
+    "./api/fragment-instantiation": {
+      "bun": "./src/api/fragment-instantiation.ts",
+      "development": "./src/api/fragment-instantiation.ts",
+      "types": "./dist/api/fragment-instantiation.d.ts",
+      "default": "./dist/api/fragment-instantiation.js"
+    },
     "./client": {
       "bun": "./src/client/client.ts",
       "development": "./src/client/client.ts",

package/src/api/fragment-builder.ts

@@ -0,0 +1,81 @@
+import type { FragnoPublicConfig } from "./fragment-instantiation";
+
+export interface FragmentDefinition<
+  TConfig,
+  TDeps = {},
+  TServices extends Record<string, unknown> = {},
+  TAdditionalContext extends Record<string, unknown> = {},
+> {
+  name: string;
+  dependencies?: (config: TConfig, options: FragnoPublicConfig) => TDeps;
+  services?: (config: TConfig, options: FragnoPublicConfig, deps: TDeps) => TServices;
+  additionalContext?: TAdditionalContext;
+}
+
+export class FragmentBuilder<
+  const TConfig,
+  const TDeps = {},
+  const TServices extends Record<string, unknown> = {},
+  const TAdditionalContext extends Record<string, unknown> = {},
+> {
+  #definition: FragmentDefinition<TConfig, TDeps, TServices, TAdditionalContext>;
+
+  constructor(definition: FragmentDefinition<TConfig, TDeps, TServices, TAdditionalContext>) {
+    this.#definition = definition;
+  }
+
+  get definition() {
+    return this.#definition;
+  }
+
+  get $requiredOptions(): FragnoPublicConfig {
+    throw new Error("Type only method. Do not call.");
+  }
+
+  withDependencies<TNewDeps>(
+    fn: (
+      context: { config: TConfig; fragnoConfig: FragnoPublicConfig } & TAdditionalContext,
+    ) => TNewDeps,
+  ): FragmentBuilder<TConfig, TNewDeps, {}, TAdditionalContext> {
+    return new FragmentBuilder<TConfig, TNewDeps, {}, TAdditionalContext>({
+      name: this.#definition.name,
+      dependencies: (config: TConfig, options: FragnoPublicConfig) => {
+        return fn({ config, fragnoConfig: options } as {
+          config: TConfig;
+          fragnoConfig: FragnoPublicConfig;
+        } & TAdditionalContext);
+      },
+      services: undefined,
+      additionalContext: this.#definition.additionalContext,
+    });
+  }
+
+  withServices<TNewServices extends Record<string, unknown>>(
+    fn: (
+      context: {
+        config: TConfig;
+        fragnoConfig: FragnoPublicConfig;
+        deps: TDeps;
+      } & TAdditionalContext,
+    ) => TNewServices,
+  ): FragmentBuilder<TConfig, TDeps, TNewServices, TAdditionalContext> {
+    return new FragmentBuilder<TConfig, TDeps, TNewServices, TAdditionalContext>({
+      name: this.#definition.name,
+      dependencies: this.#definition.dependencies,
+      services: (config: TConfig, options: FragnoPublicConfig, deps: TDeps) => {
+        return fn({ config, fragnoConfig: options, deps } as {
+          config: TConfig;
+          fragnoConfig: FragnoPublicConfig;
+          deps: TDeps;
+        } & TAdditionalContext);
+      },
+      additionalContext: this.#definition.additionalContext,
+    });
+  }
+}
+
+export function defineFragment<TConfig = {}>(name: string): FragmentBuilder<TConfig, {}, {}, {}> {
+  return new FragmentBuilder({
+    name,
+  });
+}

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

@@ -17,6 +17,7 @@ import {
   RequestMiddlewareOutputContext,
   type FragnoMiddlewareCallback,
 } from "./request-middleware";
+import type { FragmentDefinition } from "./fragment-builder";
 
 export interface FragnoPublicConfig {
   mountRoute?: string;
@@ -64,22 +65,29 @@ type HandlersByFramework = {
   "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 = {},
   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<
@@ -100,72 +108,38 @@ export type AnyFragnoFragmentSharedConfig = FragnoFragmentSharedConfig<
   readonly AnyFragnoRouteConfig[]
 >;
 
-interface FragmentDefinition<TConfig, TDeps = {}, TServices extends Record<string, unknown> = {}> {
-  name: string;
-  dependencies?: (config: TConfig) => TDeps;
-  services?: (config: TConfig, deps: TDeps) => TServices;
-}
-
-export class FragmentBuilder<TConfig, TDeps = {}, TServices extends Record<string, unknown> = {}> {
-  #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>);
-  }
-}
-
-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 =
@@ -191,8 +165,10 @@ export function createFragment<
   const fragment: FragnoInstantiatedFragment<
     FlattenRouteFactories<TRoutesOrFactories>,
     TDeps,
-    TServices
+    TServices,
+    TAdditionalContext & TOptions
   > = {
+    [instantiatedFragmentFakeSymbol]: instantiatedFragmentFakeSymbol,
     mountRoute,
     config: {
       name: definition.name,
@@ -200,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");

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";
@@ -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;

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.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";

package/src/client/solid.test.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { createClientBuilder } from "./client";
 import { useFragno, accessorToAtom, isAccessor } from "./solid";
 import { defineRoute } from "../api/route";
-import { defineFragment } from "../api/fragment";
+import { defineFragment } from "../api/fragment-builder";
 import type { FragnoPublicClientConfig } from "../mod";
 import { FragnoClientUnknownApiError } from "./client-error";
 import { createSignal, createRoot } from "solid-js";

package/src/client/vanilla.test.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { createClientBuilder } from "./client";
 import { useFragno } from "./vanilla";
 import { defineRoute } from "../api/route";
-import { defineFragment } from "../api/fragment";
+import { defineFragment } from "../api/fragment-builder";
 import type { FragnoPublicClientConfig } from "../mod";
 import { FragnoClientFetchNetworkError } from "./client-error";
 import { waitForAsyncIterator } from "../util/async";

package/src/client/vue.test.ts

@@ -2,7 +2,7 @@ import { test, expect, describe, vi, beforeEach, afterEach, assert } from "vites
 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 { refToAtom, useFragno } from "./vue";
 import { waitFor } from "@testing-library/vue";

package/src/mod.ts

@@ -1,12 +1,12 @@
+export { defineFragment, FragmentBuilder, type FragmentDefinition } from "./api/fragment-builder";
+
 export {
-  defineFragment,
   createFragment,
-  FragmentBuilder,
   type FragnoFragmentSharedConfig,
   type FragnoPublicConfig,
   type FragnoPublicClientConfig,
   type FragnoInstantiatedFragment,
-} from "./api/fragment";
+} from "./api/fragment-instantiation";
 
 export { type FragnoRouteConfig } from "./api/api";
 

package/tsdown.config.ts

@@ -4,6 +4,8 @@ export default defineConfig({
   entry: [
     "./src/mod.ts",
     "./src/api/api.ts",
+    "./src/api/fragment-builder.ts",
+    "./src/api/fragment-instantiation.ts",
     "./src/client/client.ts",
     "./src/client/vanilla.ts",
     "./src/client/client.svelte.ts",