@fragno-dev/core 0.1.11 → 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,
-> = (context: {
-  config: TConfig;
-  options: TOptions;
-  serviceDependencies?: TServiceDependencies;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-}) => FragnoInstantiatedFragment<any, any, any, any, any, any, any>;
-
-/**
- * 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;
 
@@ -224,17 +197,22 @@ export interface FragmentDefinition<
   }) => RequestContextStorage<TRequestStorage>;
 
   /**
-   * 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.
+   * Optional factory for internal data attached to fragment.$internal.
    */
-  linkedFragments?: {
-    [K in keyof TLinkedFragments]: LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>;
-  };
+  internalDataFactory?: (context: {
+    config: TConfig;
+    options: TOptions;
+    deps: TDeps;
+    services: BoundServices<TBaseServices & TServices>;
+    serviceDeps: TServiceDependencies;
+  }) => Record<string, unknown> | void;
+
+  internalRoutes?: TInternalRoutes;
 
   $serviceThisContext?: TServiceThisContext;
   $handlerThisContext?: THandlerThisContext;
   $requestStorage?: TRequestStorage;
-  $linkedFragments?: TLinkedFragments;
+  $internalRoutes?: TInternalRoutes;
 }
 
 /**
@@ -252,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;
@@ -306,9 +284,7 @@ export class FragmentDefinitionBuilder<
     options: TOptions;
     deps: TDeps;
   }) => RequestContextStorage<TRequestStorage>;
-  #linkedFragments?: {
-    [K in keyof TLinkedFragments]: LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>;
-  };
+  #internalRoutes?: TInternalRoutes;
 
   constructor(
     name: string,
@@ -364,13 +340,7 @@ export class FragmentDefinitionBuilder<
         options: TOptions;
         deps: TDeps;
       }) => RequestContextStorage<TRequestStorage>;
-      linkedFragments?: {
-        [K in keyof TLinkedFragments]: LinkedFragmentCallback<
-          TConfig,
-          TOptions,
-          TServiceDependencies
-        >;
-      };
+      internalRoutes?: TInternalRoutes;
     },
   ) {
     this.#name = name;
@@ -383,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;
     }
   }
 
@@ -426,7 +396,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     // Warn if we're discarding existing configuration
     if (
@@ -454,7 +424,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: fn,
       baseServices: undefined,
@@ -465,7 +435,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: undefined,
       createThisContext: undefined,
       getExternalStorage: undefined,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -494,7 +464,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return new FragmentDefinitionBuilder<
       TConfig,
@@ -507,7 +477,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: fn,
@@ -517,7 +487,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
       getExternalStorage: this.#getExternalStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -547,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 = {
@@ -576,7 +546,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -586,7 +556,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
       getExternalStorage: this.#getExternalStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -619,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 = {
@@ -648,7 +618,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -657,7 +627,7 @@ export class FragmentDefinitionBuilder<
       serviceDependencies: this.#serviceDependencies,
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -677,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 = {
@@ -698,7 +668,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -707,7 +677,7 @@ export class FragmentDefinitionBuilder<
       serviceDependencies: newServiceDependencies,
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -727,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 = {
@@ -750,7 +720,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -759,7 +729,7 @@ export class FragmentDefinitionBuilder<
       serviceDependencies: newServiceDependencies,
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -802,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
@@ -825,7 +795,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TNewRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -836,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,
     });
   }
 
@@ -873,7 +843,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TNewStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return new FragmentDefinitionBuilder<
       TConfig,
@@ -886,7 +856,7 @@ export class FragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TNewStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -897,7 +867,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: undefined,
       createThisContext: undefined,
       getExternalStorage: getStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     });
   }
 
@@ -937,7 +907,7 @@ export class FragmentDefinitionBuilder<
     TNewServiceThisContext,
     TNewHandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return new FragmentDefinitionBuilder<
       TConfig,
@@ -950,7 +920,7 @@ export class FragmentDefinitionBuilder<
       TNewServiceThisContext,
       TNewHandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >(this.#name, {
       dependencies: this.#dependencies,
       baseServices: this.#baseServices,
@@ -960,21 +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 are service-only (no routes) and share the same config/options as the parent.
-   * All services from the linked fragment will be available as private services.
+   * Define internal routes that will be mounted under /_internal.
    */
-  withLinkedFragment<
-    const TName extends string,
-    TCallback extends LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>,
-  >(
-    name: TName,
-    callback: TCallback,
+  withInternalRoutes<const TNewInternalRoutes extends readonly AnyRouteOrFactory[]>(
+    routes: TNewInternalRoutes,
   ): FragmentDefinitionBuilder<
     TConfig,
     TOptions,
@@ -982,20 +946,12 @@ export class FragmentDefinitionBuilder<
     TBaseServices,
     TServices,
     TServiceDependencies,
-    TPrivateServices & ExtractLinkedServices<TCallback>,
+    TPrivateServices,
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments & { [K in TName]: ReturnType<TCallback> }
+    TNewInternalRoutes
   > {
-    const newLinkedFragments = {
-      ...this.#linkedFragments,
-      [name]: callback,
-    };
-
-    // Cast is safe: We're declaring that the returned builder has TPrivateServices & ExtractLinkedServices<TCallback>,
-    // 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,
@@ -1005,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<TCallback>,
-      TServiceThisContext,
-      THandlerThisContext,
-      TRequestStorage,
-      TLinkedFragments & { [K in TName]: ReturnType<TCallback> }
-    >;
+      internalRoutes: routes,
+    });
   }
 
   /**
@@ -1043,7 +987,7 @@ export class FragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return {
       name: this.#name,
@@ -1055,7 +999,7 @@ export class FragmentDefinitionBuilder<
       createRequestStorage: this.#createRequestStorage,
       createThisContext: this.#createThisContext,
       getExternalStorage: this.#getExternalStorage,
-      linkedFragments: this.#linkedFragments,
+      internalRoutes: this.#internalRoutes,
     };
   }
 }
@@ -1082,7 +1026,7 @@ export function defineFragment<
   TServiceThisContext,
   THandlerThisContext,
   TRequestStorage,
-  {}
+  []
 > {
   return new FragmentDefinitionBuilder(name);
 }