@fragno-dev/core 0.1.7 → 0.1.8

package/src/api/route.test.ts

@@ -1,5 +1,6 @@
 import { test, expect, expectTypeOf, describe } from "vitest";
-import { defineRoute } from "./route";
+import { defineRoute, defineRoutes, type ExtractFragmentServices } from "./route";
+import { defineFragment } from "./fragment-builder";
 import { z } from "zod";
 
 describe("defineRoute", () => {
@@ -174,3 +175,112 @@ describe("defineRoute", () => {
     // Currently defineRoute doesn't enforce ValidPath constraints
   });
 });
+
+describe("ExtractFragmentServices", () => {
+  test("extracts services from fragment with .providesService()", () => {
+    const fragment = defineFragment<{}>("test-fragment")
+      .withDependencies(() => ({ dep: "value" }))
+      .providesService(({ defineService }) =>
+        defineService({
+          getUserById: async (id: string) => ({ id, name: "John" }),
+          createUser: async (name: string) => ({ id: "123", name }),
+        }),
+      );
+
+    type Services = ExtractFragmentServices<typeof fragment>;
+
+    expectTypeOf<Services>().toMatchObjectType<{
+      getUserById: (id: string) => Promise<{ id: string; name: string }>;
+      createUser: (name: string) => Promise<{ id: string; name: string }>;
+    }>();
+  });
+
+  test("ExtractFragmentServices returns never for fragment without services", () => {
+    const fragment = defineFragment<{}>("test-fragment").withDependencies(() => ({ dep: "value" }));
+
+    type Services = ExtractFragmentServices<typeof fragment>;
+
+    // Fragment with no services should have empty services object
+    expectTypeOf<Services>().toEqualTypeOf<{}>();
+  });
+});
+
+describe("defineRoutes", () => {
+  test("defineRoutes extracts services correctly for route factory", () => {
+    const fragment = defineFragment<{}>("test-fragment").providesService(({ defineService }) =>
+      defineService({
+        getUserById: async (id: string) => ({ id, name: "John" }),
+        createUser: async (name: string) => ({ id: "123", name }),
+      }),
+    );
+
+    const routeFactory = defineRoutes(fragment).create(({ services, config, deps }) => {
+      // Type check that services are properly extracted
+      expectTypeOf(services).toMatchObjectType<{
+        getUserById: (id: string) => Promise<{ id: string; name: string }>;
+        createUser: (name: string) => Promise<{ id: string; name: string }>;
+      }>();
+
+      expectTypeOf(config).toEqualTypeOf<{}>();
+      expectTypeOf(deps).toEqualTypeOf<{}>();
+
+      return [
+        defineRoute({
+          method: "GET",
+          path: "/users/:id",
+          outputSchema: z.object({ id: z.string(), name: z.string() }),
+          handler: async ({ pathParams }, { json }) => {
+            // Services should be accessible here via closure
+            const user = await services.getUserById(pathParams.id);
+            return json(user);
+          },
+        }),
+      ];
+    });
+
+    // routeFactory is a function that returns routes when called
+    expect(routeFactory).toBeDefined();
+    expect(typeof routeFactory).toBe("function");
+  });
+
+  test("defineRoutes with dependencies and services", () => {
+    const fragment = defineFragment<{ apiKey: string }>("auth-fragment")
+      .withDependencies(({ config }) => ({
+        authClient: { apiKey: config.apiKey },
+      }))
+      .providesService(({ deps, defineService }) =>
+        defineService({
+          validateToken: async (_token: string) => {
+            return { valid: true, apiKey: deps.authClient.apiKey };
+          },
+        }),
+      );
+
+    const routeFactory = defineRoutes(fragment).create(({ services, config, deps }) => {
+      // Type check all context properties
+      expectTypeOf(config).toEqualTypeOf<{ apiKey: string }>();
+      expectTypeOf(deps).toMatchObjectType<{ authClient: { apiKey: string } }>();
+      expectTypeOf(services).toMatchObjectType<{
+        validateToken: (token: string) => Promise<{ valid: boolean; apiKey: string }>;
+      }>();
+
+      return [
+        defineRoute({
+          method: "POST",
+          path: "/auth/validate",
+          inputSchema: z.object({ token: z.string() }),
+          outputSchema: z.object({ valid: z.boolean() }),
+          handler: async ({ input }, { json }) => {
+            const { token } = await input!.valid();
+            const result = await services.validateToken(token);
+            return json({ valid: result.valid });
+          },
+        }),
+      ];
+    });
+
+    // routeFactory is a function that returns routes when called
+    expect(routeFactory).toBeDefined();
+    expect(typeof routeFactory).toBe("function");
+  });
+});

package/src/api/route.ts

@@ -1,8 +1,14 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { FragnoRouteConfig, HTTPMethod } from "./api";
+import type { FragnoRouteConfig, HTTPMethod, RequestThisContext } from "./api";
+import type { FragmentDefinition } from "./fragment-builder";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AnyFragnoRouteConfig = FragnoRouteConfig<HTTPMethod, string, any, any, any, any>;
+export type AnyFragnoRouteConfig = FragnoRouteConfig<HTTPMethod, string, any, any, any, any, any>;
+
+export type AnyFragmentBuilder = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly definition: FragmentDefinition<any, any, any, any, any, any, any>;
+};
 
 export interface RouteFactoryContext<TConfig, TDeps, TServices> {
   config: TConfig;
@@ -20,7 +26,8 @@ export type RouteFactory<
     StandardSchemaV1 | undefined,
     StandardSchemaV1 | undefined,
     string,
-    string
+    string,
+    RequestThisContext
   >[],
 > = (context: RouteFactoryContext<TConfig, TDeps, TServices>) => TRoutes;
 
@@ -74,6 +81,7 @@ export function defineRoute<
   const TOutputSchema extends StandardSchemaV1 | undefined,
   const TErrorCode extends string = string,
   const TQueryParameters extends string = string,
+  const TThisContext extends RequestThisContext = RequestThisContext,
 >(
   config: FragnoRouteConfig<
     TMethod,
@@ -81,9 +89,18 @@ export function defineRoute<
     undefined,
     TOutputSchema,
     TErrorCode,
-    TQueryParameters
+    TQueryParameters,
+    TThisContext
   > & { inputSchema?: undefined },
-): FragnoRouteConfig<TMethod, TPath, undefined, TOutputSchema, TErrorCode, TQueryParameters>;
+): FragnoRouteConfig<
+  TMethod,
+  TPath,
+  undefined,
+  TOutputSchema,
+  TErrorCode,
+  TQueryParameters,
+  TThisContext
+>;
 
 // Overload for routes with inputSchema
 export function defineRoute<
@@ -93,6 +110,7 @@ export function defineRoute<
   const TOutputSchema extends StandardSchemaV1 | undefined,
   const TErrorCode extends string = string,
   const TQueryParameters extends string = string,
+  const TThisContext extends RequestThisContext = RequestThisContext,
 >(
   config: FragnoRouteConfig<
     TMethod,
@@ -100,9 +118,18 @@ export function defineRoute<
     TInputSchema,
     TOutputSchema,
     TErrorCode,
-    TQueryParameters
+    TQueryParameters,
+    TThisContext
   > & { inputSchema: TInputSchema },
-): FragnoRouteConfig<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>;
+): FragnoRouteConfig<
+  TMethod,
+  TPath,
+  TInputSchema,
+  TOutputSchema,
+  TErrorCode,
+  TQueryParameters,
+  TThisContext
+>;
 
 // implementation
 export function defineRoute<
@@ -112,6 +139,7 @@ export function defineRoute<
   const TOutputSchema extends StandardSchemaV1 | undefined,
   const TErrorCode extends string = string,
   const TQueryParameters extends string = string,
+  const TThisContext extends RequestThisContext = RequestThisContext,
 >(
   config: FragnoRouteConfig<
     TMethod,
@@ -119,13 +147,262 @@ export function defineRoute<
     TInputSchema,
     TOutputSchema,
     TErrorCode,
-    TQueryParameters
+    TQueryParameters,
+    TThisContext
   >,
-): FragnoRouteConfig<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters> {
+): FragnoRouteConfig<
+  TMethod,
+  TPath,
+  TInputSchema,
+  TOutputSchema,
+  TErrorCode,
+  TQueryParameters,
+  TThisContext
+> {
   return config;
 }
 
-export function defineRoutes<TConfig = {}, TDeps = {}, TServices = {}>() {
+// Type helpers to extract types from FragmentBuilder or DatabaseFragmentBuilder
+// DatabaseFragmentBuilder has 6 type parameters: TSchema, TConfig, TDeps, TServices, TUsedServices, TProvidedServices
+// FragmentBuilder has 6 type parameters: TConfig, TDeps, TServices, TAdditionalContext, TUsedServices, TProvidedServices
+
+// Helper to get the return type of the definition getter
+// Use T['definition'] to access the property type
+type GetDefinition<T> = T extends { definition: unknown } ? T["definition"] : never;
+
+// Extract config
+export type ExtractFragmentConfig<T> =
+  GetDefinition<T> extends FragmentDefinition<
+    infer TConfig,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any
+  >
+    ? TConfig
+    : never;
+
+// Extract deps
+export type ExtractFragmentDeps<T> =
+  GetDefinition<T> extends FragmentDefinition<
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    infer TDeps,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    infer TUsedServices,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any
+  >
+    ? TDeps & TUsedServices
+    : never;
+
+// Helper to recursively bind services (removes `this` parameter from methods)
+type OmitThisParameter<T> = T extends (this: infer _This, ...args: infer A) => infer R
+  ? (...args: A) => R
+  : T;
+
+type BoundServicesLocal<T> = {
+  [K in keyof T]: T[K] extends (...args: never[]) => unknown
+    ? OmitThisParameter<T[K]>
+    : T[K] extends Record<string, unknown>
+      ? BoundServicesLocal<T[K]>
+      : T[K];
+};
+
+// Extract services (merges both withServices and providesService)
+// First try to extract from $types if available (for DatabaseFragmentBuilder)
+// Otherwise fall back to extracting from definition
+export type ExtractFragmentServices<T> = T extends {
+  $types: { services: infer S; providedServices: infer P };
+}
+  ? BoundServicesLocal<S & P>
+  : GetDefinition<T> extends FragmentDefinition<
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        any,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        any,
+        infer TServices,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        any,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        any,
+        infer TProvidedServices
+      >
+    ? TServices & TProvidedServices
+    : never;
+
+// Extract the this context type from the fragment builder
+export type ExtractThisContext<T> =
+  GetDefinition<T> extends FragmentDefinition<
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    infer TThisContext
+  >
+    ? TThisContext
+    : RequestThisContext;
+
+// Overload that infers types from FragmentBuilder or DatabaseFragmentBuilder (runtime value)
+export function defineRoutes<const TFragmentBuilder extends AnyFragmentBuilder>(
+  fragmentBuilder: TFragmentBuilder,
+): {
+  create: <
+    const TRoutes extends readonly FragnoRouteConfig<
+      HTTPMethod,
+      string,
+      StandardSchemaV1 | undefined,
+      StandardSchemaV1 | undefined,
+      string,
+      string,
+      ExtractThisContext<TFragmentBuilder>
+    >[],
+  >(
+    fn: (
+      context: RouteFactoryContext<
+        ExtractFragmentConfig<TFragmentBuilder>,
+        ExtractFragmentDeps<TFragmentBuilder>,
+        ExtractFragmentServices<TFragmentBuilder>
+      > & {
+        defineRoute: <
+          const TMethod extends HTTPMethod,
+          const TPath extends string,
+          const TInputSchema extends StandardSchemaV1 | undefined,
+          const TOutputSchema extends StandardSchemaV1 | undefined,
+          const TErrorCode extends string = string,
+          const TQueryParameters extends string = string,
+        >(
+          config: FragnoRouteConfig<
+            TMethod,
+            TPath,
+            TInputSchema,
+            TOutputSchema,
+            TErrorCode,
+            TQueryParameters,
+            ExtractThisContext<TFragmentBuilder>
+          >,
+        ) => FragnoRouteConfig<
+          TMethod,
+          TPath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          ExtractThisContext<TFragmentBuilder>
+        >;
+      },
+    ) => TRoutes,
+  ) => RouteFactory<
+    ExtractFragmentConfig<TFragmentBuilder>,
+    ExtractFragmentDeps<TFragmentBuilder>,
+    ExtractFragmentServices<TFragmentBuilder>,
+    TRoutes
+  >;
+};
+
+// Overload that infers types from FragmentBuilder or DatabaseFragmentBuilder (type parameter)
+export function defineRoutes<const TFragmentBuilder extends AnyFragmentBuilder>(): {
+  create: <
+    const TRoutes extends readonly FragnoRouteConfig<
+      HTTPMethod,
+      string,
+      StandardSchemaV1 | undefined,
+      StandardSchemaV1 | undefined,
+      string,
+      string,
+      ExtractThisContext<TFragmentBuilder>
+    >[],
+  >(
+    fn: (
+      context: RouteFactoryContext<
+        ExtractFragmentConfig<TFragmentBuilder>,
+        ExtractFragmentDeps<TFragmentBuilder>,
+        ExtractFragmentServices<TFragmentBuilder>
+      > & {
+        defineRoute: <
+          const TMethod extends HTTPMethod,
+          const TPath extends string,
+          const TInputSchema extends StandardSchemaV1 | undefined,
+          const TOutputSchema extends StandardSchemaV1 | undefined,
+          const TErrorCode extends string = string,
+          const TQueryParameters extends string = string,
+        >(
+          config: FragnoRouteConfig<
+            TMethod,
+            TPath,
+            TInputSchema,
+            TOutputSchema,
+            TErrorCode,
+            TQueryParameters,
+            ExtractThisContext<TFragmentBuilder>
+          >,
+        ) => FragnoRouteConfig<
+          TMethod,
+          TPath,
+          TInputSchema,
+          TOutputSchema,
+          TErrorCode,
+          TQueryParameters,
+          ExtractThisContext<TFragmentBuilder>
+        >;
+      },
+    ) => TRoutes,
+  ) => RouteFactory<
+    ExtractFragmentConfig<TFragmentBuilder>,
+    ExtractFragmentDeps<TFragmentBuilder>,
+    ExtractFragmentServices<TFragmentBuilder>,
+    TRoutes
+  >;
+};
+
+// Overload that accepts manual type parameters
+export function defineRoutes<TConfig = {}, TDeps = {}, TServices = {}>(): {
+  create: <
+    const TRoutes extends readonly FragnoRouteConfig<
+      HTTPMethod,
+      string,
+      StandardSchemaV1 | undefined,
+      StandardSchemaV1 | undefined,
+      string,
+      string,
+      RequestThisContext
+    >[],
+  >(
+    fn: (
+      context: RouteFactoryContext<TConfig, TDeps, TServices> & {
+        defineRoute: typeof defineRoute;
+      },
+    ) => TRoutes,
+  ) => RouteFactory<TConfig, TDeps, TServices, TRoutes>;
+};
+
+// Implementation
+export function defineRoutes<
+  const TConfig = {},
+  const TDeps = {},
+  const TServices = {},
+  const TFragmentBuilder extends AnyFragmentBuilder | undefined = undefined,
+>(
+  // Parameter is only used for type inference, not runtime
+  _fragmentBuilder?: TFragmentBuilder,
+) {
   return {
     create: <
       const TRoutes extends readonly FragnoRouteConfig<
@@ -134,12 +411,44 @@ export function defineRoutes<TConfig = {}, TDeps = {}, TServices = {}>() {
         StandardSchemaV1 | undefined,
         StandardSchemaV1 | undefined,
         string,
-        string
+        string,
+        RequestThisContext
       >[],
     >(
-      fn: (context: RouteFactoryContext<TConfig, TDeps, TServices>) => TRoutes,
-    ): RouteFactory<TConfig, TDeps, TServices, TRoutes> => {
-      return fn;
+      fn: (
+        context: RouteFactoryContext<
+          TFragmentBuilder extends AnyFragmentBuilder
+            ? ExtractFragmentConfig<TFragmentBuilder>
+            : TConfig,
+          TFragmentBuilder extends AnyFragmentBuilder
+            ? ExtractFragmentDeps<TFragmentBuilder>
+            : TDeps,
+          TFragmentBuilder extends AnyFragmentBuilder
+            ? ExtractFragmentServices<TFragmentBuilder>
+            : TServices
+        > & {
+          defineRoute: typeof defineRoute;
+        },
+      ) => TRoutes,
+    ): RouteFactory<
+      TFragmentBuilder extends AnyFragmentBuilder
+        ? ExtractFragmentConfig<TFragmentBuilder>
+        : TConfig,
+      TFragmentBuilder extends AnyFragmentBuilder ? ExtractFragmentDeps<TFragmentBuilder> : TDeps,
+      TFragmentBuilder extends AnyFragmentBuilder
+        ? ExtractFragmentServices<TFragmentBuilder>
+        : TServices,
+      TRoutes
+    > => {
+      // Create a wrapper around the callback that adds the defineRoute function
+      return (ctx: RouteFactoryContext<unknown, unknown, unknown>) => {
+        const extendedCtx = {
+          ...ctx,
+          defineRoute,
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return fn(extendedCtx as any);
+      };
     },
   };
 }

package/src/mod.ts

@@ -1,7 +1,14 @@
-export { defineFragment, FragmentBuilder, type FragmentDefinition } from "./api/fragment-builder";
+export {
+  defineFragment,
+  FragmentBuilder,
+  type FragmentDefinition,
+  type RouteHandler,
+} from "./api/fragment-builder";
 
 export {
   createFragment,
+  instantiateFragment,
+  FragmentInstantiationBuilder,
   type FragnoFragmentSharedConfig,
   type FragnoPublicConfig,
   type FragnoPublicClientConfig,
@@ -18,3 +25,6 @@ export {
   type AnyRouteOrFactory,
   type FlattenRouteFactories,
 } from "./api/route";
+
+export { RequestInputContext } from "./api/request-input-context";
+export { RequestOutputContext } from "./api/request-output-context";

package/src/test/test.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, expectTypeOf } from "vitest";
+import { describe, it, expect, expectTypeOf, assert } from "vitest";
 import { createFragmentForTest } from "./test";
 import { defineFragment } from "../api/fragment-builder";
 import { defineRoute, defineRoutes } from "../api/route";
@@ -46,9 +46,11 @@ describe("createFragmentForTest", () => {
       .withDependencies(({ config }) => ({
         client: { apiKey: config.apiKey },
       }))
-      .withServices(({ deps }) => ({
-        getApiKey: () => deps.client.apiKey,
-      }));
+      .providesService(({ deps, defineService }) =>
+        defineService({
+          getApiKey: () => deps.client.apiKey,
+        }),
+      );
 
     const testFragment = createFragmentForTest(fragment, [], {
       config: { apiKey: "test-key" },
@@ -62,9 +64,11 @@ describe("createFragmentForTest", () => {
       .withDependencies(({ config }) => ({
         client: { apiKey: config.apiKey },
       }))
-      .withServices(({ deps }) => ({
-        getApiKey: () => deps.client.apiKey,
-      }));
+      .providesService(({ deps, defineService }) =>
+        defineService({
+          getApiKey: () => deps.client.apiKey,
+        }),
+      );
 
     const testFragment = createFragmentForTest(fragment, [], {
       config: { apiKey: "test-key" },
@@ -81,9 +85,11 @@ describe("createFragmentForTest", () => {
 
     const fragment = defineFragment<Config>("test")
       .withDependencies(() => ({ dep: "value" }))
-      .withServices(({ config }) => ({
-        multiply: (x: number) => x * config.multiplier,
-      }));
+      .providesService(({ config, defineService }) =>
+        defineService({
+          multiply: (x: number) => x * config.multiplier,
+        }),
+      );
 
     const routeFactory = defineRoutes<Config, Deps, Services>().create(({ services }) => [
       defineRoute({
@@ -233,7 +239,7 @@ describe("fragment.callRoute", () => {
   });
 
   it("should handle route factory created with defineRoutes", async () => {
-    const fragment = defineFragment<{ apiKey: string }>("test").withServices(() => ({
+    const fragment = defineFragment<{ apiKey: string }>("test").providesService(() => ({
       getGreeting: (name: string) => `Hello, ${name}!`,
       getCount: () => 42,
     }));
@@ -270,10 +276,9 @@ describe("fragment.callRoute", () => {
       pathParams: { name: "World" },
     });
 
-    expect(greetingResponse.type).toBe("json");
-    if (greetingResponse.type === "json") {
-      expect(greetingResponse.data).toEqual({ message: "Hello, World!" });
-    }
+    console.log(greetingResponse);
+    assert(greetingResponse.type === "json");
+    expect(greetingResponse.data).toEqual({ message: "Hello, World!" });
 
     // Test second route
     const countResponse = await testFragment.callRoute("GET", "/count");