@fragno-dev/core 0.1.7 → 0.1.8

package/src/api/fragment-instantiation.test.ts

@@ -1,6 +1,6 @@
 import { test, expect, describe } from "vitest";
 import { defineFragment } from "./fragment-builder";
-import { createFragment } from "./fragment-instantiation";
+import { createFragment, instantiateFragment } from "./fragment-instantiation";
 import { defineRoute, defineRoutes } from "./route";
 import { z } from "zod";
 
@@ -31,7 +31,7 @@ describe("callRoute", () => {
       body: { name: "World" },
     });
 
-    expect(response.type).toBe("json");
+    // expect(response.type).toBe("json");
     if (response.type === "json") {
       expect(response.status).toBe(200);
       expect(response.data).toEqual({ message: "Hello, World!" });
@@ -391,11 +391,13 @@ describe("callRoute", () => {
       getUserName: () => string;
     };
 
-    const fragment = defineFragment<typeof config>("test-fragment").withServices(() => {
-      return {
-        getUserName: () => "Test User",
-      };
-    });
+    const fragment = defineFragment<typeof config>("test-fragment").providesService(
+      ({ defineService }) => {
+        return defineService({
+          getUserName: () => "Test User",
+        });
+      },
+    );
 
     const routesFactory = defineRoutes<typeof config, {}, Services>().create(({ services }) => {
       return [
@@ -457,4 +459,244 @@ describe("callRoute", () => {
       expect(response.data).toEqual({ result: "database-result" });
     }
   });
+
+  test("this context is RequestThisContext for standard fragments", async () => {
+    const config = {};
+
+    const fragment = defineFragment<typeof config>("test-fragment");
+
+    const routesFactory = defineRoutes<typeof config>().create(() => {
+      return [
+        defineRoute({
+          method: "GET",
+          path: "/context-test",
+          outputSchema: z.object({ contextType: z.string() }),
+          handler: async function (_, { json }) {
+            // this should be RequestThisContext (empty object by default)
+            expect(this).toBeDefined();
+            expect(typeof this).toBe("object");
+            return json({ contextType: "standard" });
+          },
+        }),
+      ];
+    });
+
+    const instance = createFragment(fragment, config, [routesFactory], {});
+
+    const response = await instance.callRoute("GET", "/context-test");
+
+    expect(response.type).toBe("json");
+    if (response.type === "json") {
+      expect(response.status).toBe(200);
+      expect(response.data).toEqual({ contextType: "standard" });
+    }
+  });
+
+  test("route handlers receive correct this context at runtime", async () => {
+    const fragment = defineFragment("this-test");
+
+    const routesFactory = defineRoutes(fragment).create(({ defineRoute }) => {
+      return [
+        defineRoute({
+          method: "GET",
+          path: "/this-test",
+          outputSchema: z.object({ hasThis: z.boolean() }),
+          handler: async function (_, { json }) {
+            // Verify that 'this' is defined and is an object
+            const hasThis = this !== undefined && typeof this === "object";
+            return json({ hasThis });
+          },
+        }),
+      ];
+    });
+
+    const instance = createFragment(fragment, {}, [routesFactory], {});
+
+    const response = await instance.callRoute("GET", "/this-test");
+
+    expect(response.type).toBe("json");
+    if (response.type === "json") {
+      expect(response.status).toBe(200);
+      expect(response.data).toEqual({ hasThis: true });
+    }
+  });
+});
+
+describe("FragmentInstantiationBuilder", () => {
+  describe("instantiate", () => {
+    test("basic instantiation with defaults", () => {
+      const fragment = defineFragment<{ apiKey: string }>("test");
+
+      const instance = instantiateFragment(fragment).build();
+
+      expect(instance.config.name).toBe("test");
+      expect(instance.deps).toEqual({});
+      expect(instance.services).toEqual({});
+    });
+
+    test("with config", () => {
+      const fragment = defineFragment<{ apiKey: string }>("test");
+
+      const instance = instantiateFragment(fragment).withConfig({ apiKey: "test-key" }).build();
+
+      expect(instance.config.name).toBe("test");
+    });
+
+    test("with routes", async () => {
+      const fragment = defineFragment<{}>("test");
+
+      const route = defineRoute({
+        method: "GET",
+        path: "/hello",
+        outputSchema: z.object({ message: z.string() }),
+        handler: async (_ctx, { json }) => json({ message: "hello" }),
+      });
+
+      const instance = instantiateFragment(fragment).withConfig({}).withRoutes([route]).build();
+
+      const response = await instance.callRoute("GET", "/hello");
+
+      expect(response.type).toBe("json");
+      if (response.type === "json") {
+        expect(response.data).toEqual({ message: "hello" });
+      }
+    });
+
+    test("with options", () => {
+      const fragment = defineFragment<{}>("test");
+
+      const instance = instantiateFragment(fragment)
+        .withConfig({})
+        .withOptions({ mountRoute: "/custom" })
+        .build();
+
+      expect(instance.mountRoute).toBe("/custom");
+    });
+
+    test("with services (used services)", () => {
+      interface IEmailService {
+        sendEmail(to: string, subject: string): Promise<void>;
+      }
+
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const fragment = defineFragment<{}>("test").usesService<"email", IEmailService>("email");
+
+      const instance = instantiateFragment(fragment)
+        .withConfig({})
+        .withServices({ email: emailImpl })
+        .build();
+
+      expect(instance.services.email).toBeDefined();
+      expect(instance.services.email.sendEmail).toBeDefined();
+    });
+
+    test("all options together", async () => {
+      interface ILogger {
+        log(message: string): void;
+      }
+
+      const loggerImpl: ILogger = {
+        log: () => {},
+      };
+
+      const fragment = defineFragment<{ apiKey: string }>("test")
+        .withDependencies(({ config }) => ({
+          client: { key: config.apiKey },
+        }))
+        .usesService<"logger", ILogger>("logger");
+
+      const route = defineRoute({
+        method: "GET",
+        path: "/test",
+        outputSchema: z.object({ success: z.boolean() }),
+        handler: async (_ctx, { json }) => json({ success: true }),
+      });
+
+      const instance = instantiateFragment(fragment)
+        .withConfig({ apiKey: "my-key" })
+        .withRoutes([route])
+        .withOptions({ mountRoute: "/api" })
+        .withServices({ logger: loggerImpl })
+        .build();
+
+      expect(instance.config.name).toBe("test");
+      expect(instance.mountRoute).toBe("/api");
+      expect(instance.deps.client.key).toBe("my-key");
+      expect(instance.services.logger).toBeDefined();
+
+      const response = await instance.callRoute("GET", "/test");
+      expect(response.type).toBe("json");
+      if (response.type === "json") {
+        expect(response.data).toEqual({ success: true });
+      }
+    });
+
+    test("method chaining is fluent", () => {
+      const fragment = defineFragment<{ apiKey: string }>("test");
+
+      // Should be chainable
+      const builder = instantiateFragment(fragment)
+        .withConfig({ apiKey: "key" })
+        .withRoutes([])
+        .withOptions({});
+
+      expect(builder).toBeDefined();
+      expect(typeof builder.build).toBe("function");
+    });
+
+    test("config defaults to empty object", () => {
+      const fragment = defineFragment<{}>("test");
+
+      const instance = instantiateFragment(fragment).build();
+
+      expect(instance).toBeDefined();
+    });
+
+    test("routes defaults to empty array", () => {
+      const fragment = defineFragment<{}>("test");
+
+      const instance = instantiateFragment(fragment).withConfig({}).build();
+
+      expect(instance.config.routes).toEqual([]);
+    });
+
+    test("options defaults to empty object", () => {
+      const fragment = defineFragment<{}>("test");
+
+      const instance = instantiateFragment(fragment).withConfig({}).build();
+
+      // Default mountRoute is generated
+      expect(instance.mountRoute).toContain("/test");
+    });
+
+    test("services are optional if not required", () => {
+      interface ILogger {
+        log(message: string): void;
+      }
+
+      const fragment = defineFragment<{}>("test").usesService<"logger", ILogger>("logger", {
+        optional: true,
+      });
+
+      // Should not throw even without providing the service
+      const instance = instantiateFragment(fragment).withConfig({}).build();
+
+      expect(instance).toBeDefined();
+    });
+
+    test("throws when required service not provided", () => {
+      interface IEmailService {
+        sendEmail(to: string): Promise<void>;
+      }
+
+      const fragment = defineFragment<{}>("test").usesService<"email", IEmailService>("email");
+
+      expect(() => {
+        instantiateFragment(fragment).withConfig({}).build();
+      }).toThrow("Fragment 'test' requires service 'email' but it was not provided");
+    });
+  });
 });

package/src/api/fragment-instantiation.ts

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { type FragnoRouteConfig, type HTTPMethod } from "./api";
+import { type FragnoRouteConfig, type HTTPMethod, type RequestThisContext } from "./api";
 import { FragnoApiError } from "./error";
 import { getMountRoute } from "./internal/route";
 import { addRoute, createRouter, findRoute } from "rou3";
@@ -17,7 +17,7 @@ import {
   RequestMiddlewareOutputContext,
   type FragnoMiddlewareCallback,
 } from "./request-middleware";
-import type { FragmentDefinition } from "./fragment-builder";
+import type { FragmentDefinition, RouteHandler } from "./fragment-builder";
 import { MutableRequestState } from "./mutable-request-state";
 import type { RouteHandlerInputOptions } from "./route-handler-input-options";
 import type { ExtractRouteByPath, ExtractRoutePath } from "../client/client";
@@ -147,29 +147,94 @@ export function createFragment<
   const TServices extends Record<string, unknown>,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
   const TAdditionalContext extends Record<string, unknown>,
+  const TRequiredInterfaces extends Record<string, unknown>,
+  const TProvidedInterfaces extends Record<string, unknown>,
   const TOptions extends FragnoPublicConfig,
+  const TThisContext extends RequestThisContext = RequestThisContext,
 >(
   fragmentBuilder: {
-    definition: FragmentDefinition<TConfig, TDeps, TServices, TAdditionalContext>;
+    definition: FragmentDefinition<
+      TConfig,
+      TDeps,
+      TServices,
+      TAdditionalContext,
+      TRequiredInterfaces,
+      TProvidedInterfaces,
+      TThisContext
+    >;
     $requiredOptions: TOptions;
   },
   config: TConfig,
   routesOrFactories: TRoutesOrFactories,
   options: TOptions,
+  interfaceImplementations?: TRequiredInterfaces,
 ): FragnoInstantiatedFragment<
   FlattenRouteFactories<TRoutesOrFactories>,
-  TDeps,
-  TServices,
+  TDeps & TRequiredInterfaces,
+  TServices & TProvidedInterfaces & TRequiredInterfaces,
   TAdditionalContext
 > {
   type TRoutes = FlattenRouteFactories<TRoutesOrFactories>;
 
   const definition = fragmentBuilder.definition;
 
+  // Validate required services are satisfied
+  if (definition.usedServices) {
+    for (const [serviceName, serviceMeta] of Object.entries(definition.usedServices)) {
+      const implementation = interfaceImplementations?.[serviceName];
+      if (serviceMeta.required && !implementation) {
+        throw new Error(
+          `Fragment '${definition.name}' requires service '${serviceMeta.name}' but it was not provided`,
+        );
+      }
+    }
+  }
+
   const dependencies = definition.dependencies?.(config, options) ?? ({} as TDeps);
-  const services = definition.services?.(config, options, dependencies) ?? ({} as TServices);
 
-  const context = { config, deps: dependencies, services };
+  // Merge interface implementations into dependencies
+  const depsWithInterfaces = {
+    ...dependencies,
+    ...interfaceImplementations,
+  } as TDeps & TRequiredInterfaces;
+
+  const servicesFromWithServices =
+    definition.services?.(config, options, depsWithInterfaces) ?? ({} as TServices);
+
+  // Handle providedServices - can be:
+  // 1. A function that returns all services
+  // 2. An object where each value is a factory function
+  // 3. undefined
+  let providedServicesResolved: TProvidedInterfaces | undefined;
+
+  if (typeof definition.providedServices === "function") {
+    // Case 1: It's a function, call it to get the services
+    providedServicesResolved = definition.providedServices(config, options, depsWithInterfaces);
+  } else if (definition.providedServices && typeof definition.providedServices === "object") {
+    // Case 2: It's an object where each value might be a factory function
+    providedServicesResolved = {} as TProvidedInterfaces;
+    for (const [serviceName, serviceOrFactory] of Object.entries(definition.providedServices)) {
+      if (typeof serviceOrFactory === "function") {
+        // Call the factory function
+        (providedServicesResolved as Record<string, unknown>)[serviceName] = serviceOrFactory(
+          config,
+          options,
+          depsWithInterfaces,
+        );
+      } else {
+        // It's already a resolved service
+        (providedServicesResolved as Record<string, unknown>)[serviceName] = serviceOrFactory;
+      }
+    }
+  }
+
+  const services = {
+    ...servicesFromWithServices,
+    ...providedServicesResolved,
+    ...interfaceImplementations,
+  } as TServices & TProvidedInterfaces & TRequiredInterfaces;
+
+  const context = { config, deps: depsWithInterfaces, services };
   const routes = resolveRouteFactories(context, routesOrFactories);
 
   const mountRoute = getMountRoute({
@@ -185,22 +250,30 @@ export function createFragment<
         StandardSchemaV1 | undefined,
         StandardSchemaV1 | undefined,
         string,
-        string
+        string,
+        RequestThisContext
       >
     >();
 
   let middlewareHandler:
-    | FragnoMiddlewareCallback<FlattenRouteFactories<TRoutesOrFactories>, TDeps, TServices>
+    | FragnoMiddlewareCallback<
+        FlattenRouteFactories<TRoutesOrFactories>,
+        TDeps & TRequiredInterfaces,
+        TServices & TProvidedInterfaces & TRequiredInterfaces
+      >
     | undefined;
 
+  // Store the handler wrapper if provided (e.g., for database support)
+  const handlerWrapper = definition.createHandlerWrapper?.(options);
+
   for (const routeConfig of routes) {
     addRoute(router, routeConfig.method.toUpperCase(), routeConfig.path, routeConfig);
   }
 
   const fragment: FragnoInstantiatedFragment<
     FlattenRouteFactories<TRoutesOrFactories>,
-    TDeps,
-    TServices,
+    TDeps & TRequiredInterfaces,
+    TServices & TProvidedInterfaces & TRequiredInterfaces,
     TAdditionalContext & TOptions
   > = {
     [instantiatedFragmentFakeSymbol]: instantiatedFragmentFakeSymbol,
@@ -210,7 +283,7 @@ export function createFragment<
       routes,
     },
     services,
-    deps: dependencies,
+    deps: depsWithInterfaces,
     additionalContext: {
       ...definition.additionalContext,
       ...options,
@@ -297,9 +370,25 @@ export function createFragment<
       // Construct RequestOutputContext
       const outputContext = new RequestOutputContext(route.outputSchema);
 
-      // Call the route handler
+      // Call the route handler (wrap with handlerWrapper if provided)
       try {
-        const response = await route.handler(inputContext, outputContext);
+        let response: Response;
+        const thisContext: RequestThisContext = {};
+
+        if (handlerWrapper) {
+          // Wrapper handles binding the this context internally for database fragments
+          // Safe: wrapper knows how to handle the specific this type (DatabaseRequestThisContext)
+          const wrappedHandler = handlerWrapper(route.handler as unknown as RouteHandler);
+          response = await wrappedHandler.call(thisContext, inputContext, outputContext);
+        } else {
+          // For standard fragments, bind to an empty RequestThisContext
+          // Safe: we know route.handler expects RequestThisContext for standard fragments
+          response = await (route.handler as RouteHandler).call(
+            thisContext,
+            inputContext,
+            outputContext,
+          );
+        }
         return response;
       } catch (error) {
         console.error("Error in callRoute handler", error);
@@ -440,7 +529,10 @@ export function createFragment<
           state: requestState,
         });
 
-        const middlewareOutputContext = new RequestMiddlewareOutputContext(dependencies, services);
+        const middlewareOutputContext = new RequestMiddlewareOutputContext(
+          depsWithInterfaces,
+          services,
+        );
 
         try {
           const middlewareResult = await middlewareHandler(
@@ -478,7 +570,16 @@ export function createFragment<
       });
 
       try {
-        const result = await handler(inputContext, outputContext);
+        // Apply handler wrapper if provided (e.g., for database support)
+        // Safe cast: handler wrapper preserves handler signature
+        const actualHandler = handlerWrapper
+          ? (handlerWrapper(handler as RouteHandler) as typeof handler)
+          : handler;
+
+        // Create base this context (empty object for standard fragments)
+        // Database fragments will provide their own context via handler wrapper
+        const thisContext = {} as RequestThisContext;
+        const result = await actualHandler.call(thisContext, inputContext, outputContext);
         return result;
       } catch (error) {
         console.error("Error in handler", error);
@@ -497,3 +598,169 @@ export function createFragment<
 
   return fragment;
 }
+
+/**
+ * Builder class for fluent fragment instantiation API
+ */
+export class FragmentInstantiationBuilder<
+  TConfig,
+  TDeps,
+  TServices extends Record<string, unknown>,
+  TRoutesOrFactories extends readonly AnyRouteOrFactory[],
+  TAdditionalContext extends Record<string, unknown>,
+  TRequiredInterfaces extends Record<string, unknown>,
+  TProvidedInterfaces extends Record<string, unknown>,
+  TOptions extends FragnoPublicConfig,
+  TThisContext extends RequestThisContext,
+> {
+  #fragmentBuilder: {
+    definition: FragmentDefinition<
+      TConfig,
+      TDeps,
+      TServices,
+      TAdditionalContext,
+      TRequiredInterfaces,
+      TProvidedInterfaces,
+      TThisContext
+    >;
+    $requiredOptions: TOptions;
+  };
+  #config?: TConfig;
+  #routes?: TRoutesOrFactories;
+  #options?: TOptions;
+  #services?: TRequiredInterfaces;
+
+  constructor(fragmentBuilder: {
+    definition: FragmentDefinition<
+      TConfig,
+      TDeps,
+      TServices,
+      TAdditionalContext,
+      TRequiredInterfaces,
+      TProvidedInterfaces,
+      TThisContext
+    >;
+    $requiredOptions: TOptions;
+  }) {
+    this.#fragmentBuilder = fragmentBuilder;
+  }
+
+  /**
+   * Set the configuration for the fragment
+   */
+  withConfig(config: TConfig): this {
+    this.#config = config;
+    return this;
+  }
+
+  /**
+   * Set the routes for the fragment
+   */
+  withRoutes<const TNewRoutes extends readonly AnyRouteOrFactory[]>(
+    routes: TNewRoutes,
+  ): FragmentInstantiationBuilder<
+    TConfig,
+    TDeps,
+    TServices,
+    TNewRoutes,
+    TAdditionalContext,
+    TRequiredInterfaces,
+    TProvidedInterfaces,
+    TOptions,
+    TThisContext
+  > {
+    this.#routes = routes as unknown as TRoutesOrFactories;
+    // Safe cast: We're changing the route type parameter
+    return this as unknown as FragmentInstantiationBuilder<
+      TConfig,
+      TDeps,
+      TServices,
+      TNewRoutes,
+      TAdditionalContext,
+      TRequiredInterfaces,
+      TProvidedInterfaces,
+      TOptions,
+      TThisContext
+    >;
+  }
+
+  /**
+   * Set the options for the fragment (e.g., mountRoute, databaseAdapter)
+   */
+  withOptions(options: TOptions): this {
+    this.#options = options;
+    return this;
+  }
+
+  /**
+   * Provide implementations for services that this fragment uses
+   */
+  withServices(services: TRequiredInterfaces): this {
+    this.#services = services;
+    return this;
+  }
+
+  /**
+   * Build and return the instantiated fragment
+   */
+  build(): FragnoInstantiatedFragment<
+    FlattenRouteFactories<TRoutesOrFactories>,
+    TDeps & TRequiredInterfaces,
+    TServices & TProvidedInterfaces & TRequiredInterfaces,
+    TAdditionalContext
+  > {
+    return createFragment(
+      this.#fragmentBuilder,
+      this.#config ?? ({} as TConfig),
+      this.#routes ?? ([] as const as unknown as TRoutesOrFactories),
+      this.#options ?? ({} as TOptions),
+      this.#services,
+    );
+  }
+}
+
+/**
+ * Create a fluent builder for instantiating a fragment
+ *
+ * @example
+ * ```ts
+ * const fragment = instantiateFragment(myFragmentBuilder)
+ *   .withConfig({ apiKey: "key" })
+ *   .withRoutes([route1, route2])
+ *   .withOptions({ mountRoute: "/api" })
+ *   .build();
+ * ```
+ */
+export function instantiateFragment<
+  TConfig,
+  TDeps,
+  TServices extends Record<string, unknown>,
+  TAdditionalContext extends Record<string, unknown>,
+  TRequiredInterfaces extends Record<string, unknown>,
+  TProvidedInterfaces extends Record<string, unknown>,
+  TOptions extends FragnoPublicConfig,
+  TThisContext extends RequestThisContext = RequestThisContext,
+>(fragmentBuilder: {
+  definition: FragmentDefinition<
+    TConfig,
+    TDeps,
+    TServices,
+    TAdditionalContext,
+    TRequiredInterfaces,
+    TProvidedInterfaces,
+    TThisContext
+  >;
+  $requiredOptions: TOptions;
+}): FragmentInstantiationBuilder<
+  TConfig,
+  TDeps,
+  TServices,
+  readonly [],
+  TAdditionalContext,
+  TRequiredInterfaces,
+  TProvidedInterfaces,
+  TOptions,
+  TThisContext
+> {
+  return new FragmentInstantiationBuilder(fragmentBuilder);
+}