@fragno-dev/core 0.2.0 → 0.2.2

package/src/api/fragment-definition-builder.ts

@@ -1,10 +1,8 @@
 import type { RequestThisContext } from "./api";
-import type { FragnoPublicConfig } from "./shared-types";
+import type { BoundServices } from "./bind-services";
 import type { RequestContextStorage } from "./request-context-storage";
-import type {
-  FragnoInstantiatedFragment,
-  AnyFragnoInstantiatedFragment,
-} from "./fragment-instantiator";
+import type { AnyRouteOrFactory } from "./route";
+import type { FragnoPublicConfig } from "./shared-types";
 
 /**
  * Metadata for a service dependency
@@ -16,31 +14,6 @@ interface ServiceMetadata {
   required: boolean;
 }
 
-/**
- * Callback that instantiates a linked fragment.
- * Receives the same context as the main fragment and returns an instantiated fragment.
- */
-export type LinkedFragmentCallback<
-  TConfig,
-  TOptions extends FragnoPublicConfig,
-  TServiceDependencies,
-  TFragment extends AnyFragnoInstantiatedFragment = AnyFragnoInstantiatedFragment,
-> = (context: {
-  config: TConfig;
-  options: TOptions;
-  serviceDependencies?: TServiceDependencies;
-}) => TFragment;
-
-/**
- * Extract the services type from a FragnoInstantiatedFragment
- */
-export type ExtractLinkedServices<T> = T extends (
-  ...args: never[]
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-) => FragnoInstantiatedFragment<any, any, infer TServices, any, any, any, any>
-  ? TServices
-  : never;
-
 /**
  * Context passed to the request context factory function.
  */
@@ -116,7 +89,7 @@ export interface FragmentDefinition<
   TServiceThisContext extends RequestThisContext,
   THandlerThisContext extends RequestThisContext,
   TRequestStorage = {},
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},
+  TInternalRoutes extends readonly AnyRouteOrFactory[] = readonly [],
 > {
   name: string;
 
@@ -230,26 +203,16 @@ export interface FragmentDefinition<
     config: TConfig;
     options: TOptions;
     deps: TDeps;
-    linkedFragments: TLinkedFragments;
+    services: BoundServices<TBaseServices & TServices>;
+    serviceDeps: TServiceDependencies;
   }) => Record<string, unknown> | void;
 
-  /**
-   * Optional linked fragments that will be automatically instantiated with this fragment.
-   * Linked fragments are service-only and share the same config/options as the parent.
-   */
-  linkedFragments?: {
-    [K in keyof TLinkedFragments]: LinkedFragmentCallback<
-      TConfig,
-      TOptions,
-      TServiceDependencies,
-      TLinkedFragments[K]
-    >;
-  };
+  internalRoutes?: TInternalRoutes;
 
   $serviceThisContext?: TServiceThisContext;
   $handlerThisContext?: THandlerThisContext;
   $requestStorage?: TRequestStorage;
-  $linkedFragments?: TLinkedFragments;
+  $internalRoutes?: TInternalRoutes;
 }
 
 /**
@@ -267,7 +230,7 @@ export class FragmentDefinitionBuilder<
   TServiceThisContext extends RequestThisContext,
   THandlerThisContext extends RequestThisContext,
   TRequestStorage = {},
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},
+  TInternalRoutes extends readonly AnyRouteOrFactory[] = readonly [],
 > {
   #name: string;
   #dependencies?: (context: { config: TConfig; options: TOptions }) => TDeps;
@@ -321,14 +284,7 @@ export class FragmentDefinitionBuilder<
     options: TOptions;
     deps: TDeps;
   }) => RequestContextStorage<TRequestStorage>;
-  #linkedFragments?: {
-    [K in keyof TLinkedFragments]: LinkedFragmentCallback<
-      TConfig,
-      TOptions,
-      TServiceDependencies,
-      TLinkedFragments[K]
-    >;
-  };
+  #internalRoutes?: TInternalRoutes;
 
   constructor(
     name: string,
@@ -384,14 +340,7 @@ export class FragmentDefinitionBuilder<
         options: TOptions;
         deps: TDeps;
       }) => RequestContextStorage<TRequestStorage>;
-      linkedFragments?: {
-        [K in keyof TLinkedFragments]: LinkedFragmentCallback<
-          TConfig,
-          TOptions,
-          TServiceDependencies,
-          TLinkedFragments[K]
-        >;
-      };
+      internalRoutes?: TInternalRoutes;
     },
   ) {
     this.#name = name;
@@ -404,7 +353,7 @@ export class FragmentDefinitionBuilder<
       this.#createRequestStorage = state.createRequestStorage;
       this.#createThisContext = state.createThisContext;
       this.#getExternalStorage = state.getExternalStorage;
-      this.#linkedFragments = state.linkedFragments;
+      this.#internalRoutes = state.internalRoutes;
     }
   }
 
@@ -447,7 +396,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     // Warn if we're discarding existing configuration
     if (
@@ -475,7 +424,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: fn,
       baseServices: undefined,
@@ -486,7 +435,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: undefined,
       createThisContext: undefined,
       getExternalStorage: undefined,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -515,7 +464,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return new FragmentDefinitionBuilder<
       TConfig,
@@ -528,7 +477,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: fn,
@@ -538,7 +487,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
       getExternalStorage: this.#getExternalStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -568,7 +517,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     // Type assertion needed because TypeScript can't verify object spread with mapped types
     const newNamedServices = {
@@ -597,7 +546,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -607,7 +556,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
       getExternalStorage: this.#getExternalStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -640,7 +589,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     // Type assertion needed because TypeScript can't verify object spread with mapped types
     const newPrivateServices = {
@@ -669,7 +618,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -678,7 +627,7 @@ export class FragmentDefinitionBuilder<
       serviceDependencies: this.#serviceDependencies,
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -698,7 +647,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     // Type assertion needed because TypeScript can't verify object spread with mapped types
     const newServiceDependencies = {
@@ -719,7 +668,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -728,7 +677,7 @@ export class FragmentDefinitionBuilder<
       serviceDependencies: newServiceDependencies,
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -748,7 +697,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     // Type assertion needed because TypeScript can't verify object spread with mapped types
     const newServiceDependencies = {
@@ -771,7 +720,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -780,7 +729,7 @@ export class FragmentDefinitionBuilder<
       serviceDependencies: newServiceDependencies,
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -823,7 +772,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TNewRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     // getExternalStorage can coexist with createRequestStorage (they work together)
     // Cast is safe when storage type changes: the external storage container adapts to hold the new type
@@ -846,7 +795,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TNewRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -857,7 +806,7 @@ export class FragmentDefinitionBuilder<
       // Reset context function since storage type changed - it must be reconfigured
       createThisContext: undefined,
       getExternalStorage: preservedExternalStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -894,7 +843,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TNewStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return new FragmentDefinitionBuilder<
       TConfig,
@@ -907,7 +856,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TNewStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -918,7 +867,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: undefined,
       createThisContext: undefined,
       getExternalStorage: getStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -958,7 +907,7 @@ export class FragmentDefinitionBuilder<
     TNewServiceThisContext,
     TNewHandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return new FragmentDefinitionBuilder<
       TConfig,
@@ -971,7 +920,7 @@ export class FragmentDefinitionBuilder<
       TNewServiceThisContext,
       TNewHandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -981,19 +930,15 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: this.#createRequestStorage,
       createThisContext: fn,
       getExternalStorage: this.#getExternalStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
   /**
-   * Register a linked fragment that will be automatically instantiated.
-   * Linked fragments share the same config/options as the parent and their services
-   * are exposed as private services. Routes are not exposed by default, but the
-   * instantiator may mount internal linked fragment routes under an internal prefix.
+   * Define internal routes that will be mounted under /_internal.
    */
-  withLinkedFragment<const TName extends string, TFragment extends AnyFragnoInstantiatedFragment>(
-    name: TName,
-    callback: LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies, TFragment>,
+  withInternalRoutes<const TNewInternalRoutes extends readonly AnyRouteOrFactory[]>(
+    routes: TNewInternalRoutes,
   ): FragmentDefinitionBuilder<
     TConfig,
     TOptions,
@@ -1001,20 +946,12 @@ export class FragmentDefinitionBuilder<
     TBaseServices,
     TServices,
     TServiceDependencies,
-    TPrivateServices & ExtractLinkedServices<() => TFragment>,
+    TPrivateServices,
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments & { [K in TName]: TFragment }
+    TNewInternalRoutes
   > {
-    const newLinkedFragments = {
-      ...this.#linkedFragments,
-      [name]: callback,
-    };
-
-    // Cast is safe: We're declaring that the returned builder has TPrivateServices & ExtractLinkedServices<TFragment>,
-    // even though the runtime privateServices hasn't changed yet. The linked fragment services will be
-    // merged into privateServices at instantiation time by the instantiator.
     return new FragmentDefinitionBuilder(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -1024,20 +961,8 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
       getExternalStorage: this.#getExternalStorage,
-      linkedFragments: newLinkedFragments,
-    }) as FragmentDefinitionBuilder<
-      TConfig,
-      TOptions,
-      TDeps,
-      TBaseServices,
-      TServices,
-      TServiceDependencies,
-      TPrivateServices & ExtractLinkedServices<() => TFragment>,
-      TServiceThisContext,
-      THandlerThisContext,
-      TRequestStorage,
-      TLinkedFragments & { [K in TName]: TFragment }
-    >;
+      internalRoutes: routes,
+    });
   }
 
   /**
@@ -1062,7 +987,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return {
       name: this.#name,
@@ -1074,7 +999,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
       getExternalStorage: this.#getExternalStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     };
   }
 }
@@ -1101,7 +1026,7 @@ export function defineFragment<
   TServiceThisContext,
   THandlerThisContext,
   TRequestStorage,
-  {}
+  []
 > {
   return new FragmentDefinitionBuilder(name);
 }