@fragno-dev/core 0.1.7 → 0.1.9

package/dist/api/fragment-definition-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment-definition-builder.js","names":["#name","#dependencies","#baseServices","#namedServices","#privateServices","#serviceDependencies","#createRequestStorage","#createThisContext","#getExternalStorage","#linkedFragments"],"sources":["../../src/api/fragment-definition-builder.ts"],"sourcesContent":["import type { RequestThisContext } from \"./api\";\nimport type { FragnoPublicConfig } from \"./shared-types\";\nimport type { RequestContextStorage } from \"./request-context-storage\";\nimport type {\n  FragnoInstantiatedFragment,\n  AnyFragnoInstantiatedFragment,\n} from \"./fragment-instantiator\";\n\n/**\n * Metadata for a service dependency\n */\ninterface ServiceMetadata {\n  /** Name of the service */\n  name: string;\n  /** Whether this service is required (false means optional) */\n  required: boolean;\n}\n\n/**\n * Callback that instantiates a linked fragment.\n * Receives the same context as the main fragment and returns an instantiated fragment.\n */\nexport type LinkedFragmentCallback<\n  TConfig,\n  TOptions extends FragnoPublicConfig,\n  TServiceDependencies,\n> = (context: {\n  config: TConfig;\n  options: TOptions;\n  serviceDependencies?: TServiceDependencies;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n}) => FragnoInstantiatedFragment<any, any, any, any, any, any, any>;\n\n/**\n * Extract the services type from a FragnoInstantiatedFragment\n */\nexport type ExtractLinkedServices<T> = T extends (\n  ...args: never[]\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n) => FragnoInstantiatedFragment<any, any, infer TServices, any, any, any, any>\n  ? TServices\n  : never;\n\n/**\n * Context passed to the request context factory function.\n */\nexport type RequestContextFactoryContext<\n  TConfig,\n  TOptions extends FragnoPublicConfig,\n  TDeps,\n  TRequestStorage,\n> = {\n  config: TConfig;\n  options: TOptions;\n  deps: TDeps;\n  storage: RequestContextStorage<TRequestStorage>;\n};\n\n/**\n * Context object passed to service constructor functions\n */\nexport type ServiceContext<\n  TConfig,\n  TOptions,\n  TDeps,\n  TServiceDependencies,\n  TPrivateServices,\n  TServiceThisContext extends RequestThisContext,\n> = {\n  config: TConfig;\n  options: TOptions;\n  deps: TDeps;\n  serviceDeps: TServiceDependencies;\n  privateServices: TPrivateServices;\n  /**\n   * Helper to define services with proper `this` context typing.\n   * Use this to wrap your service methods when they need access to `this`.\n   */\n  defineService: <T>(svc: T & ThisType<TServiceThisContext>) => T;\n};\n\n/**\n * Service constructor function type\n */\nexport type ServiceConstructorFn<\n  TConfig,\n  TOptions,\n  TDeps,\n  TServiceDependencies,\n  TPrivateServices,\n  TService,\n  TServiceThisContext extends RequestThisContext,\n> = (\n  context: ServiceContext<\n    TConfig,\n    TOptions,\n    TDeps,\n    TServiceDependencies,\n    TPrivateServices,\n    TServiceThisContext\n  >,\n) => TService;\n\n/**\n * Fragment definition interface that supports both regular and database fragments.\n * This is the core definition that will be used for fragment instantiation.\n */\nexport interface FragmentDefinition<\n  TConfig,\n  TOptions extends FragnoPublicConfig,\n  TDeps,\n  TBaseServices,\n  TServices,\n  TServiceDependencies,\n  TPrivateServices,\n  TServiceThisContext extends RequestThisContext,\n  THandlerThisContext extends RequestThisContext,\n  TRequestStorage = {},\n  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},\n> {\n  name: string;\n\n  // Core callbacks - all take context objects with separate deps and serviceDeps\n  dependencies?: (context: { config: TConfig; options: TOptions }) => TDeps;\n\n  baseServices?: ServiceConstructorFn<\n    TConfig,\n    TOptions,\n    TDeps,\n    TServiceDependencies,\n    TPrivateServices,\n    TBaseServices,\n    TServiceThisContext\n  >;\n\n  // Named services stored as factory functions\n  namedServices?: {\n    [K in keyof TServices]: ServiceConstructorFn<\n      TConfig,\n      TOptions,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TServices[K],\n      TServiceThisContext\n    >;\n  };\n\n  // Private services - only accessible internally when defining other services\n  privateServices?: {\n    [K in keyof TPrivateServices]: ServiceConstructorFn<\n      TConfig,\n      TOptions,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices, // Private services can access other private services\n      TPrivateServices[K],\n      TServiceThisContext\n    >;\n  };\n\n  // Service dependency metadata\n  serviceDependencies?: {\n    [K in keyof TServiceDependencies]: ServiceMetadata;\n  };\n\n  /**\n   * Optional factory function to create the initial request storage data.\n   * This is called at the start of each request to initialize the storage.\n   * The returned object can be mutated throughout the request lifecycle.\n   *\n   * @example\n   * ```ts\n   * createRequestStorage: ({ config, options, deps }) => ({\n   *   counter: 0,\n   *   userId: deps.currentUserId\n   * })\n   * ```\n   */\n  createRequestStorage?: (context: {\n    config: TConfig;\n    options: TOptions;\n    deps: TDeps;\n  }) => TRequestStorage;\n\n  /**\n   * Optional factory function to create the this contexts for services and handlers.\n   * Returns separate contexts: serviceContext (may be restricted) and handlerContext (full access).\n   * Both contexts should contain only methods or getters that read from storage.\n   *\n   * @example\n   * ```ts\n   * createThisContext: ({ storage }) => ({\n   *   serviceContext: {\n   *     getUnitOfWork: () => restrictedUOW  // Without execute methods\n   *   },\n   *   handlerContext: {\n   *     getUnitOfWork: () => fullUOW  // With execute methods\n   *   }\n   * })\n   * ```\n   */\n  createThisContext?: (\n    context: RequestContextFactoryContext<TConfig, TOptions, TDeps, TRequestStorage>,\n  ) => {\n    serviceContext: TServiceThisContext;\n    handlerContext: THandlerThisContext;\n  };\n\n  /**\n   * Optional factory function to get an external RequestContextStorage instance.\n   * When provided, this storage will be used instead of creating a new one.\n   * This allows multiple fragments to share the same storage (e.g., database fragments sharing adapter storage).\n   *\n   * @example\n   * ```ts\n   * getExternalStorage: ({ options }) => options.databaseAdapter.contextStorage\n   * ```\n   */\n  getExternalStorage?: (context: {\n    config: TConfig;\n    options: TOptions;\n    deps: TDeps;\n  }) => RequestContextStorage<TRequestStorage>;\n\n  /**\n   * Optional linked fragments that will be automatically instantiated with this fragment.\n   * Linked fragments are service-only and share the same config/options as the parent.\n   */\n  linkedFragments?: {\n    [K in keyof TLinkedFragments]: LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>;\n  };\n\n  $serviceThisContext?: TServiceThisContext;\n  $handlerThisContext?: THandlerThisContext;\n  $requestStorage?: TRequestStorage;\n  $linkedFragments?: TLinkedFragments;\n}\n\n/**\n * Builder class for creating fragment definitions.\n * This provides a fluent API for defining fragments with type safety.\n */\nexport class FragmentDefinitionBuilder<\n  TConfig,\n  TOptions extends FragnoPublicConfig,\n  TDeps,\n  TBaseServices,\n  TServices,\n  TServiceDependencies,\n  TPrivateServices,\n  TServiceThisContext extends RequestThisContext,\n  THandlerThisContext extends RequestThisContext,\n  TRequestStorage = {},\n  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},\n> {\n  #name: string;\n  #dependencies?: (context: { config: TConfig; options: TOptions }) => TDeps;\n  #baseServices?: ServiceConstructorFn<\n    TConfig,\n    TOptions,\n    TDeps,\n    TServiceDependencies,\n    TPrivateServices,\n    TBaseServices,\n    TServiceThisContext\n  >;\n  #namedServices?: {\n    [K in keyof TServices]: ServiceConstructorFn<\n      TConfig,\n      TOptions,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TServices[K],\n      TServiceThisContext\n    >;\n  };\n  #privateServices?: {\n    [K in keyof TPrivateServices]: ServiceConstructorFn<\n      TConfig,\n      TOptions,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TPrivateServices[K],\n      TServiceThisContext\n    >;\n  };\n  #serviceDependencies?: {\n    [K in keyof TServiceDependencies]: ServiceMetadata;\n  };\n  #createRequestStorage?: (context: {\n    config: TConfig;\n    options: TOptions;\n    deps: TDeps;\n  }) => TRequestStorage;\n  #createThisContext?: (\n    context: RequestContextFactoryContext<TConfig, TOptions, TDeps, TRequestStorage>,\n  ) => {\n    serviceContext: TServiceThisContext;\n    handlerContext: THandlerThisContext;\n  };\n  #getExternalStorage?: (context: {\n    config: TConfig;\n    options: TOptions;\n    deps: TDeps;\n  }) => RequestContextStorage<TRequestStorage>;\n  #linkedFragments?: {\n    [K in keyof TLinkedFragments]: LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>;\n  };\n\n  constructor(\n    name: string,\n    state?: {\n      dependencies?: (context: { config: TConfig; options: TOptions }) => TDeps;\n      baseServices?: ServiceConstructorFn<\n        TConfig,\n        TOptions,\n        TDeps,\n        TServiceDependencies,\n        TPrivateServices,\n        TBaseServices,\n        TServiceThisContext\n      >;\n      namedServices?: {\n        [K in keyof TServices]: ServiceConstructorFn<\n          TConfig,\n          TOptions,\n          TDeps,\n          TServiceDependencies,\n          TPrivateServices,\n          TServices[K],\n          TServiceThisContext\n        >;\n      };\n      privateServices?: {\n        [K in keyof TPrivateServices]: ServiceConstructorFn<\n          TConfig,\n          TOptions,\n          TDeps,\n          TServiceDependencies,\n          TPrivateServices,\n          TPrivateServices[K],\n          TServiceThisContext\n        >;\n      };\n      serviceDependencies?: {\n        [K in keyof TServiceDependencies]: ServiceMetadata;\n      };\n      createRequestStorage?: (context: {\n        config: TConfig;\n        options: TOptions;\n        deps: TDeps;\n      }) => TRequestStorage;\n      createThisContext?: (\n        context: RequestContextFactoryContext<TConfig, TOptions, TDeps, TRequestStorage>,\n      ) => {\n        serviceContext: TServiceThisContext;\n        handlerContext: THandlerThisContext;\n      };\n      getExternalStorage?: (context: {\n        config: TConfig;\n        options: TOptions;\n        deps: TDeps;\n      }) => RequestContextStorage<TRequestStorage>;\n      linkedFragments?: {\n        [K in keyof TLinkedFragments]: LinkedFragmentCallback<\n          TConfig,\n          TOptions,\n          TServiceDependencies\n        >;\n      };\n    },\n  ) {\n    this.#name = name;\n    if (state) {\n      this.#dependencies = state.dependencies;\n      this.#baseServices = state.baseServices;\n      this.#namedServices = state.namedServices;\n      this.#privateServices = state.privateServices;\n      this.#serviceDependencies = state.serviceDependencies;\n      this.#createRequestStorage = state.createRequestStorage;\n      this.#createThisContext = state.createThisContext;\n      this.#getExternalStorage = state.getExternalStorage;\n      this.#linkedFragments = state.linkedFragments;\n    }\n  }\n\n  get name(): string {\n    return this.#name;\n  }\n\n  /**\n   * Define dependencies for this fragment.\n   * Dependencies are available to services and handlers.\n   *\n   * **IMPORTANT**: This method resets all services, storage, and context configurations.\n   * Always call `withDependencies` early in the builder chain, before defining services\n   * or request storage/context.\n   *\n   * @example\n   * ```typescript\n   * // ✅ GOOD: Dependencies set first\n   * defineFragment(\"my-fragment\")\n   *   .withDependencies(() => ({ apiKey: \"...\" }))\n   *   .withRequestStorage(({ deps }) => ({ userId: deps.apiKey }))\n   *   .providesService(\"myService\", ...)\n   *\n   * // ❌ BAD: Dependencies set late (erases storage setup)\n   * defineFragment(\"my-fragment\")\n   *   .withRequestStorage(() => ({ userId: \"...\" }))  // This gets erased!\n   *   .withDependencies(() => ({ apiKey: \"...\" }))\n   * ```\n   */\n  withDependencies<TNewDeps>(\n    fn: (context: { config: TConfig; options: TOptions }) => TNewDeps,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TNewDeps,\n    {},\n    {},\n    TServiceDependencies,\n    {},\n    TServiceThisContext,\n    THandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments\n  > {\n    // Warn if we're discarding existing configuration\n    if (\n      this.#baseServices ||\n      this.#namedServices ||\n      this.#privateServices ||\n      this.#createRequestStorage ||\n      this.#createThisContext ||\n      this.#getExternalStorage\n    ) {\n      console.warn(\n        `[Fragno] Warning: withDependencies() on fragment \"${this.#name}\" is resetting previously configured services, request storage, or request context. ` +\n          `To avoid this, call withDependencies() earlier in the builder chain, before configuring services or storage.`,\n      );\n    }\n\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TNewDeps,\n      {},\n      {},\n      TServiceDependencies,\n      {},\n      TServiceThisContext,\n      THandlerThisContext,\n      TRequestStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: fn,\n      baseServices: undefined,\n      namedServices: undefined,\n      privateServices: undefined,\n      serviceDependencies: this.#serviceDependencies,\n      // Reset storage/context functions since deps type changed - they must be reconfigured\n      createRequestStorage: undefined,\n      createThisContext: undefined,\n      getExternalStorage: undefined,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Define base (unnamed) services for this fragment.\n   * Base services are accessible directly on the fragment instance.\n   */\n  providesBaseService<TNewService>(\n    fn: ServiceConstructorFn<\n      TConfig,\n      TOptions,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TNewService,\n      TServiceThisContext\n    >,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TNewService,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments\n  > {\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TNewService,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices,\n      TServiceThisContext,\n      THandlerThisContext,\n      TRequestStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: fn,\n      namedServices: this.#namedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: this.#serviceDependencies,\n      createRequestStorage: this.#createRequestStorage,\n      createThisContext: this.#createThisContext,\n      getExternalStorage: this.#getExternalStorage,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Provide a named service that other fragments or users can use.\n   * Named services are accessible as fragment.serviceName.method()\n   */\n  providesService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n    fn: ServiceConstructorFn<\n      TConfig,\n      TOptions,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TService,\n      TServiceThisContext\n    >,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices & { [K in TServiceName]: TService },\n    TServiceDependencies,\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments\n  > {\n    // Type assertion needed because TypeScript can't verify object spread with mapped types\n    const newNamedServices = {\n      ...this.#namedServices,\n      [serviceName]: fn,\n    } as {\n      [K in keyof (TServices & { [K in TServiceName]: TService })]: ServiceConstructorFn<\n        TConfig,\n        TOptions,\n        TDeps,\n        TServiceDependencies,\n        TPrivateServices,\n        (TServices & { [K in TServiceName]: TService })[K],\n        TServiceThisContext\n      >;\n    };\n\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TBaseServices,\n      TServices & { [K in TServiceName]: TService },\n      TServiceDependencies,\n      TPrivateServices,\n      TServiceThisContext,\n      THandlerThisContext,\n      TRequestStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: newNamedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: this.#serviceDependencies,\n      createRequestStorage: this.#createRequestStorage,\n      createThisContext: this.#createThisContext,\n      getExternalStorage: this.#getExternalStorage,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Provide a private service that is only accessible to the fragment author.\n   * Private services are NOT exposed on the fragment instance, but can be used\n   * when defining other services (baseServices, namedServices, and other privateServices).\n   * Private services are instantiated in order, so earlier private services are available\n   * to later ones.\n   */\n  providesPrivateService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n    fn: ServiceConstructorFn<\n      TConfig,\n      TOptions,\n      TDeps,\n      TServiceDependencies,\n      TPrivateServices,\n      TService,\n      TServiceThisContext\n    >,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices & { [K in TServiceName]: TService },\n    TServiceThisContext,\n    THandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments\n  > {\n    // Type assertion needed because TypeScript can't verify object spread with mapped types\n    const newPrivateServices = {\n      ...this.#privateServices,\n      [serviceName]: fn,\n    } as {\n      [K in keyof (TPrivateServices & { [K in TServiceName]: TService })]: ServiceConstructorFn<\n        TConfig,\n        TOptions,\n        TDeps,\n        TServiceDependencies,\n        TPrivateServices & { [K in TServiceName]: TService },\n        (TPrivateServices & { [K in TServiceName]: TService })[K],\n        TServiceThisContext\n      >;\n    };\n\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices & { [K in TServiceName]: TService },\n      TServiceThisContext,\n      THandlerThisContext,\n      TRequestStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: this.#namedServices,\n      privateServices: newPrivateServices,\n      serviceDependencies: this.#serviceDependencies,\n      createRequestStorage: this.#createRequestStorage,\n      createThisContext: this.#createThisContext,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Declare that this fragment uses a required service provided by the runtime.\n   */\n  usesService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies & { [K in TServiceName]: TService },\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments\n  > {\n    // Type assertion needed because TypeScript can't verify object spread with mapped types\n    const newServiceDependencies = {\n      ...this.#serviceDependencies,\n      [serviceName]: { name: serviceName, required: true },\n    } as {\n      [K in keyof (TServiceDependencies & { [K in TServiceName]: TService })]: ServiceMetadata;\n    };\n\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies & { [K in TServiceName]: TService },\n      TPrivateServices,\n      TServiceThisContext,\n      THandlerThisContext,\n      TRequestStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: this.#namedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: newServiceDependencies,\n      createRequestStorage: this.#createRequestStorage,\n      createThisContext: this.#createThisContext,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Declare that this fragment uses an optional service provided by the runtime.\n   */\n  usesOptionalService<TServiceName extends string, TService>(\n    serviceName: TServiceName,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies & { [K in TServiceName]: TService | undefined },\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments\n  > {\n    // Type assertion needed because TypeScript can't verify object spread with mapped types\n    const newServiceDependencies = {\n      ...this.#serviceDependencies,\n      [serviceName]: { name: serviceName, required: false },\n    } as {\n      [K in keyof (TServiceDependencies & {\n        [K in TServiceName]: TService | undefined;\n      })]: ServiceMetadata;\n    };\n\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies & { [K in TServiceName]: TService | undefined },\n      TPrivateServices,\n      TServiceThisContext,\n      THandlerThisContext,\n      TRequestStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: this.#namedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: newServiceDependencies,\n      createRequestStorage: this.#createRequestStorage,\n      createThisContext: this.#createThisContext,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Define the type and initial data stored in AsyncLocalStorage for per-request isolation.\n   * This should be called before withThisContext if you need to store request-specific data.\n   *\n   * @param initializer Function that returns the initial storage data for each request\n   *\n   * @example\n   * ```typescript\n   * .withRequestStorage(({ config, options, deps }) => ({\n   *   counter: 0,\n   *   userId: deps.currentUserId\n   * }))\n   * .withThisContext(({ storage }) => ({\n   *   serviceContext: {\n   *     get counter() { return storage.getStore()!.counter; }\n   *   },\n   *   handlerContext: {\n   *     get counter() { return storage.getStore()!.counter; }\n   *   }\n   * }))\n   * ```\n   */\n  withRequestStorage<TNewRequestStorage>(\n    initializer: (context: {\n      config: TConfig;\n      options: TOptions;\n      deps: TDeps;\n    }) => TNewRequestStorage,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    TNewRequestStorage,\n    TLinkedFragments\n  > {\n    // getExternalStorage can coexist with createRequestStorage (they work together)\n    // Cast is safe when storage type changes: the external storage container adapts to hold the new type\n    const preservedExternalStorage = this.#getExternalStorage\n      ? (this.#getExternalStorage as unknown as (context: {\n          config: TConfig;\n          options: TOptions;\n          deps: TDeps;\n        }) => RequestContextStorage<TNewRequestStorage>)\n      : undefined;\n\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices,\n      TServiceThisContext,\n      THandlerThisContext,\n      TNewRequestStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: this.#namedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: this.#serviceDependencies,\n      createRequestStorage: initializer,\n      // Reset context function since storage type changed - it must be reconfigured\n      createThisContext: undefined,\n      getExternalStorage: preservedExternalStorage,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Use an externally-provided RequestContextStorage instance.\n   * This allows multiple fragments to share the same storage instance.\n   * Useful when fragments need to coordinate (e.g., database fragments sharing adapter storage).\n   * Note: You must still call withRequestStorage to provide the initial storage data.\n   *\n   * @example\n   * ```typescript\n   * .withExternalRequestStorage(({ options }) =>\n   *   options.databaseAdapter.contextStorage\n   * )\n   * .withRequestStorage(({ options }) => ({\n   *   uow: options.databaseAdapter.db.createUnitOfWork()\n   * }))\n   * ```\n   */\n  withExternalRequestStorage<TNewStorage>(\n    getStorage: (context: {\n      config: TConfig;\n      options: TOptions;\n      deps: TDeps;\n    }) => RequestContextStorage<TNewStorage>,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    TNewStorage,\n    TLinkedFragments\n  > {\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices,\n      TServiceThisContext,\n      THandlerThisContext,\n      TNewStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: this.#namedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: this.#serviceDependencies,\n      // Reset storage/context functions since storage type changed - they must be reconfigured\n      createRequestStorage: undefined,\n      createThisContext: undefined,\n      getExternalStorage: getStorage,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Set the this contexts for services and handlers in this fragment.\n   * Both contexts should contain only methods or getters that read from storage.\n   * This ensures proper per-request isolation via AsyncLocalStorage.\n   *\n   * @example\n   * ```ts\n   * .withThisContext(({ storage }) => ({\n   *   serviceContext: {\n   *     get myNumber() { return storage.getStore()?.myNumber ?? 0; }\n   *   },\n   *   handlerContext: {\n   *     get myNumber() { return storage.getStore()?.myNumber ?? 0; }\n   *   }\n   * }))\n   * ```\n   */\n  withThisContext<\n    TNewServiceThisContext extends RequestThisContext,\n    TNewHandlerThisContext extends RequestThisContext,\n  >(\n    fn: (context: RequestContextFactoryContext<TConfig, TOptions, TDeps, TRequestStorage>) => {\n      serviceContext: TNewServiceThisContext;\n      handlerContext: TNewHandlerThisContext;\n    },\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TNewServiceThisContext,\n    TNewHandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments\n  > {\n    return new FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices,\n      TNewServiceThisContext,\n      TNewHandlerThisContext,\n      TRequestStorage,\n      TLinkedFragments\n    >(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: this.#namedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: this.#serviceDependencies,\n      createRequestStorage: this.#createRequestStorage,\n      createThisContext: fn,\n      getExternalStorage: this.#getExternalStorage,\n      linkedFragments: this.#linkedFragments,\n    });\n  }\n\n  /**\n   * Register a linked fragment that will be automatically instantiated.\n   * Linked fragments are service-only (no routes) and share the same config/options as the parent.\n   * All services from the linked fragment will be available as private services.\n   */\n  withLinkedFragment<\n    const TName extends string,\n    TCallback extends LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>,\n  >(\n    name: TName,\n    callback: TCallback,\n  ): FragmentDefinitionBuilder<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices & ExtractLinkedServices<TCallback>,\n    TServiceThisContext,\n    THandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments & { [K in TName]: ReturnType<TCallback> }\n  > {\n    const newLinkedFragments = {\n      ...this.#linkedFragments,\n      [name]: callback,\n    };\n\n    // Cast is safe: We're declaring that the returned builder has TPrivateServices & ExtractLinkedServices<TCallback>,\n    // even though the runtime privateServices hasn't changed yet. The linked fragment services will be\n    // merged into privateServices at instantiation time by the instantiator.\n    return new FragmentDefinitionBuilder(this.#name, {\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: this.#namedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: this.#serviceDependencies,\n      createRequestStorage: this.#createRequestStorage,\n      createThisContext: this.#createThisContext,\n      getExternalStorage: this.#getExternalStorage,\n      linkedFragments: newLinkedFragments,\n    }) as FragmentDefinitionBuilder<\n      TConfig,\n      TOptions,\n      TDeps,\n      TBaseServices,\n      TServices,\n      TServiceDependencies,\n      TPrivateServices & ExtractLinkedServices<TCallback>,\n      TServiceThisContext,\n      THandlerThisContext,\n      TRequestStorage,\n      TLinkedFragments & { [K in TName]: ReturnType<TCallback> }\n    >;\n  }\n\n  /**\n   * Extend this builder with a transformation function.\n   * This enables fluent API extensions like `.extend(withDatabase(schema))`.\n   */\n  extend<const TNewBuilder>(transformer: (builder: this) => TNewBuilder): TNewBuilder {\n    return transformer(this);\n  }\n\n  /**\n   * Build the final fragment definition\n   */\n  build(): FragmentDefinition<\n    TConfig,\n    TOptions,\n    TDeps,\n    TBaseServices,\n    TServices,\n    TServiceDependencies,\n    TPrivateServices,\n    TServiceThisContext,\n    THandlerThisContext,\n    TRequestStorage,\n    TLinkedFragments\n  > {\n    return {\n      name: this.#name,\n      dependencies: this.#dependencies,\n      baseServices: this.#baseServices,\n      namedServices: this.#namedServices,\n      privateServices: this.#privateServices,\n      serviceDependencies: this.#serviceDependencies,\n      createRequestStorage: this.#createRequestStorage,\n      createThisContext: this.#createThisContext,\n      getExternalStorage: this.#getExternalStorage,\n      linkedFragments: this.#linkedFragments,\n    };\n  }\n}\n\n/**\n * Create a new fragment definition builder\n */\nexport function defineFragment<\n  TConfig = {},\n  TOptions extends FragnoPublicConfig = FragnoPublicConfig,\n  TServiceThisContext extends RequestThisContext = RequestThisContext,\n  THandlerThisContext extends RequestThisContext = RequestThisContext,\n  TRequestStorage = {},\n>(\n  name: string,\n): FragmentDefinitionBuilder<\n  TConfig,\n  TOptions,\n  {},\n  {},\n  {},\n  {},\n  {},\n  TServiceThisContext,\n  THandlerThisContext,\n  TRequestStorage,\n  {}\n> {\n  return new FragmentDefinitionBuilder(name);\n}\n"],"mappings":"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"}

package/dist/api/fragment-instantiator.d.ts

@@ -0,0 +1,216 @@
+import { InferOrUnknown } from "../util/types-util.js";
+import { RouteHandlerInputOptions } from "./route-handler-input-options.js";
+import { FragnoPublicConfig } from "./shared-types.js";
+import { FragnoRouteConfig, HTTPMethod, RequestThisContext } from "./api.js";
+import { RequestContextStorage } from "./request-context-storage.js";
+import { BoundServices } from "./bind-services.js";
+import { AnyFragnoRouteConfig, AnyRouteOrFactory, FlattenRouteFactories } from "./route.js";
+import { ExtractRouteByPath, ExtractRoutePath } from "../client/client.js";
+import { FragnoMiddlewareCallback } from "./request-middleware.js";
+import { FragnoResponse } from "./fragno-response.js";
+import { instantiatedFragmentFakeSymbol } from "../internal/symbols.js";
+import { FragmentDefinition } from "./fragment-definition-builder.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/api/fragment-instantiator.d.ts
+type AstroHandlers = {
+  ALL: (req: Request) => Promise<Response>;
+};
+type ReactRouterHandlers = {
+  loader: (args: {
+    request: Request;
+  }) => Promise<Response>;
+  action: (args: {
+    request: Request;
+  }) => Promise<Response>;
+};
+type SolidStartHandlers = {
+  GET: (args: {
+    request: Request;
+  }) => Promise<Response>;
+  POST: (args: {
+    request: Request;
+  }) => Promise<Response>;
+  PUT: (args: {
+    request: Request;
+  }) => Promise<Response>;
+  DELETE: (args: {
+    request: Request;
+  }) => Promise<Response>;
+  PATCH: (args: {
+    request: Request;
+  }) => Promise<Response>;
+  HEAD: (args: {
+    request: Request;
+  }) => Promise<Response>;
+  OPTIONS: (args: {
+    request: Request;
+  }) => Promise<Response>;
+};
+type TanStackStartHandlers = SolidStartHandlers;
+type StandardHandlers = {
+  GET: (req: Request) => Promise<Response>;
+  POST: (req: Request) => Promise<Response>;
+  PUT: (req: Request) => Promise<Response>;
+  DELETE: (req: Request) => Promise<Response>;
+  PATCH: (req: Request) => Promise<Response>;
+  HEAD: (req: Request) => Promise<Response>;
+  OPTIONS: (req: Request) => Promise<Response>;
+};
+type HandlersByFramework = {
+  astro: AstroHandlers;
+  "react-router": ReactRouterHandlers;
+  "next-js": StandardHandlers;
+  "svelte-kit": StandardHandlers;
+  "solid-start": SolidStartHandlers;
+  "tanstack-start": TanStackStartHandlers;
+};
+type FullstackFrameworks = keyof HandlersByFramework;
+type AnyFragnoInstantiatedFragment = FragnoInstantiatedFragment<any, any, any, any, any, any, any, any>;
+interface FragnoFragmentSharedConfig<TRoutes extends readonly FragnoRouteConfig<HTTPMethod, string, StandardSchemaV1 | undefined, StandardSchemaV1 | undefined, string, string>[]> {
+  name: string;
+  routes: TRoutes;
+}
+/**
+ * Instantiated fragment class with encapsulated state.
+ * Provides the same public API as the old FragnoInstantiatedFragment but with better encapsulation.
+ */
+declare class FragnoInstantiatedFragment<TRoutes extends readonly AnyFragnoRouteConfig[], TDeps, TServices extends Record<string, unknown>, TServiceThisContext extends RequestThisContext, THandlerThisContext extends RequestThisContext, TRequestStorage = {}, TOptions extends FragnoPublicConfig = FragnoPublicConfig, TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {}> {
+  #private;
+  readonly [instantiatedFragmentFakeSymbol]: "$fragno-instantiated-fragment";
+  constructor(params: {
+    name: string;
+    routes: TRoutes;
+    deps: TDeps;
+    services: TServices;
+    mountRoute: string;
+    serviceThisContext?: TServiceThisContext;
+    handlerThisContext?: THandlerThisContext;
+    storage: RequestContextStorage<TRequestStorage>;
+    createRequestStorage?: () => TRequestStorage;
+    options: TOptions;
+    linkedFragments?: TLinkedFragments;
+  });
+  get name(): string;
+  get routes(): TRoutes;
+  get services(): TServices;
+  get mountRoute(): string;
+  /**
+   * @internal
+   */
+  get $internal(): {
+    deps: TDeps;
+    options: TOptions;
+    linkedFragments: TLinkedFragments;
+  };
+  /**
+   * Add middleware to this fragment.
+   * Middleware can inspect and modify requests before they reach handlers.
+   */
+  withMiddleware(handler: FragnoMiddlewareCallback<TRoutes, TDeps, TServices>): this;
+  /**
+   * Execute a callback within a request context.
+   * Establishes an async context for the duration of the callback, allowing services
+   * to access the `this` context. The callback's `this` will be bound to the fragment's
+   * handler context (with full capabilities including execute methods).
+   * Useful for calling services outside of route handlers (e.g., in tests, background jobs).
+   *
+   * @param callback - The callback to run within the context
+   *
+   * @example
+   * ```typescript
+   * const result = await fragment.inContext(function () {
+   *   // `this` is bound to the handler context (can call execute methods)
+   *   await this.getUnitOfWork().executeRetrieve();
+   *   return this.someContextMethod();
+   * });
+   * ```
+   */
+  inContext<T>(callback: (this: THandlerThisContext) => T): T;
+  inContext<T>(callback: (this: THandlerThisContext) => Promise<T>): Promise<T>;
+  /**
+   * Get framework-specific handlers for this fragment.
+   * Use this to integrate the fragment with different fullstack frameworks.
+   */
+  handlersFor<T extends FullstackFrameworks>(framework: T): HandlersByFramework[T];
+  /**
+   * Main request handler for this fragment.
+   * Handles routing, middleware, and error handling.
+   */
+  handler(req: Request): Promise<Response>;
+  /**
+   * Call a route directly with typed inputs and outputs.
+   * Useful for testing and server-side route calls.
+   */
+  callRoute<TMethod extends HTTPMethod, TPath extends ExtractRoutePath<TRoutes, TMethod>>(method: TMethod, path: TPath, inputOptions?: RouteHandlerInputOptions<TPath, ExtractRouteByPath<TRoutes, TPath, TMethod>["inputSchema"]>): Promise<FragnoResponse<InferOrUnknown<NonNullable<ExtractRouteByPath<TRoutes, TPath, TMethod>["outputSchema"]>>>>;
+  /**
+   * Call a route directly and get the raw Response object.
+   * Useful for testing and server-side route calls.
+   */
+  callRouteRaw<TMethod extends HTTPMethod, TPath extends ExtractRoutePath<TRoutes, TMethod>>(method: TMethod, path: TPath, inputOptions?: RouteHandlerInputOptions<TPath, ExtractRouteByPath<TRoutes, TPath, TMethod>["inputSchema"]>): Promise<Response>;
+}
+/**
+ * Core instantiation function that creates a fragment instance from a definition.
+ * This function validates dependencies, calls all callbacks, and wires everything together.
+ */
+declare function instantiateFragment<const TConfig, const TOptions extends FragnoPublicConfig, const TDeps, const TBaseServices extends Record<string, unknown>, const TServices extends Record<string, unknown>, const TServiceDependencies, const TPrivateServices extends Record<string, unknown>, const TServiceThisContext extends RequestThisContext, const THandlerThisContext extends RequestThisContext, const TRequestStorage, const TRoutesOrFactories extends readonly AnyRouteOrFactory[], const TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>>(definition: FragmentDefinition<TConfig, TOptions, TDeps, TBaseServices, TServices, TServiceDependencies, TPrivateServices, TServiceThisContext, THandlerThisContext, TRequestStorage, TLinkedFragments>, config: TConfig, routesOrFactories: TRoutesOrFactories, options: TOptions, serviceImplementations?: TServiceDependencies): FragnoInstantiatedFragment<FlattenRouteFactories<TRoutesOrFactories>, TDeps, BoundServices<TBaseServices & TServices>, TServiceThisContext, THandlerThisContext, TRequestStorage, TOptions, TLinkedFragments>;
+/**
+ * Fluent builder for instantiating fragments.
+ * Provides a type-safe API for configuring and building fragment instances.
+ */
+declare class FragmentInstantiationBuilder<TConfig, TOptions extends FragnoPublicConfig, TDeps, TBaseServices extends Record<string, unknown>, TServices extends Record<string, unknown>, TServiceDependencies, TPrivateServices extends Record<string, unknown>, TServiceThisContext extends RequestThisContext, THandlerThisContext extends RequestThisContext, TRequestStorage, TRoutesOrFactories extends readonly AnyRouteOrFactory[], TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>> {
+  #private;
+  constructor(definition: FragmentDefinition<TConfig, TOptions, TDeps, TBaseServices, TServices, TServiceDependencies, TPrivateServices, TServiceThisContext, THandlerThisContext, TRequestStorage, TLinkedFragments>, routes?: TRoutesOrFactories);
+  /**
+   * Get the fragment definition
+   */
+  get definition(): FragmentDefinition<TConfig, TOptions, TDeps, TBaseServices, TServices, TServiceDependencies, TPrivateServices, TServiceThisContext, THandlerThisContext, TRequestStorage, TLinkedFragments>;
+  /**
+   * Get the configured routes
+   */
+  get routes(): TRoutesOrFactories;
+  /**
+   * Get the configuration
+   */
+  get config(): TConfig | undefined;
+  /**
+   * Get the options
+   */
+  get options(): TOptions | undefined;
+  /**
+   * Set the configuration for the fragment
+   */
+  withConfig(config: TConfig): this;
+  /**
+   * Set the routes for the fragment
+   */
+  withRoutes<const TNewRoutes extends readonly AnyRouteOrFactory[]>(routes: TNewRoutes): FragmentInstantiationBuilder<TConfig, TOptions, TDeps, TBaseServices, TServices, TServiceDependencies, TPrivateServices, TServiceThisContext, THandlerThisContext, TRequestStorage, TNewRoutes, TLinkedFragments>;
+  /**
+   * Set the options for the fragment (e.g., mountRoute, databaseAdapter)
+   */
+  withOptions(options: TOptions): this;
+  /**
+   * Provide implementations for services that this fragment uses
+   */
+  withServices(services: TServiceDependencies): this;
+  /**
+   * Build and return the instantiated fragment
+   */
+  build(): FragnoInstantiatedFragment<FlattenRouteFactories<TRoutesOrFactories>, TDeps, BoundServices<TBaseServices & TServices>, TServiceThisContext, THandlerThisContext, TRequestStorage, TOptions, TLinkedFragments>;
+}
+/**
+ * Create a fluent builder for instantiating a fragment.
+ *
+ * @example
+ * ```ts
+ * const fragment = instantiate(myFragmentDefinition)
+ *   .withConfig({ apiKey: "key" })
+ *   .withRoutes([route1, route2])
+ *   .withOptions({ mountRoute: "/api" })
+ *   .build();
+ * ```
+ */
+declare function instantiate<TConfig, TOptions extends FragnoPublicConfig, TDeps, TBaseServices extends Record<string, unknown>, TServices extends Record<string, unknown>, TServiceDependencies, TPrivateServices extends Record<string, unknown>, TServiceThisContext extends RequestThisContext, THandlerThisContext extends RequestThisContext, TRequestStorage, TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>>(definition: FragmentDefinition<TConfig, TOptions, TDeps, TBaseServices, TServices, TServiceDependencies, TPrivateServices, TServiceThisContext, THandlerThisContext, TRequestStorage, TLinkedFragments>): FragmentInstantiationBuilder<TConfig, TOptions, TDeps, TBaseServices, TServices, TServiceDependencies, TPrivateServices, TServiceThisContext, THandlerThisContext, TRequestStorage, readonly [], TLinkedFragments>;
+//#endregion
+export { type AnyFragnoInstantiatedFragment, type BoundServices, FragmentInstantiationBuilder, FragnoFragmentSharedConfig, FragnoInstantiatedFragment, instantiate, instantiateFragment };
+//# sourceMappingURL=fragment-instantiator.d.ts.map

package/dist/api/fragment-instantiator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment-instantiator.d.ts","names":[],"sources":["../../src/api/fragment-instantiator.ts"],"sourcesContent":[],"mappings":"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"}