@fragno-dev/db 0.1.13 → 0.1.14

package/src/fragment.ts

@@ -1,7 +1,79 @@
 import type { AnySchema } from "./schema/create";
 import type { AbstractQuery } from "./query/query";
 import type { DatabaseAdapter } from "./adapters/adapters";
-import type { FragnoPublicConfig, FragmentDefinition } from "@fragno-dev/core";
+import { bindServicesToContext, type BoundServices } from "./bind-services";
+import { AsyncLocalStorage } from "async_hooks";
+import type { IUnitOfWorkBase, UnitOfWorkSchemaView } from "./query/unit-of-work";
+import type { RequestThisContext } from "@fragno-dev/core/api";
+
+export const uowStorage = new AsyncLocalStorage<IUnitOfWorkBase>();
+
+/**
+ * Service context for database fragments, providing access to the Unit of Work.
+ */
+export interface DatabaseRequestThisContext extends RequestThisContext {
+  /**
+   * Get the Unit of Work from the current context.
+   * @param schema - Optional schema to get a typed view. If not provided, returns the base UOW.
+   * @returns IUnitOfWorkBase if no schema provided, or typed UnitOfWorkSchemaView if schema provided.
+   */
+  getUnitOfWork(): IUnitOfWorkBase;
+  getUnitOfWork<TSchema extends AnySchema>(
+    schema: TSchema,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): UnitOfWorkSchemaView<TSchema, [], any>;
+}
+
+export const serviceContext: DatabaseRequestThisContext = {
+  getUnitOfWork<TSchema extends AnySchema>(
+    schema?: TSchema,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): any {
+    const uow = uowStorage.getStore();
+    if (!uow) {
+      throw new Error("No UnitOfWork in context. Service must be called within a route handler.");
+    }
+    if (schema) {
+      return uow.forSchema(schema);
+    }
+    return uow;
+  },
+};
+
+export function withUnitOfWork<T>(uow: IUnitOfWorkBase, callback: () => T): Promise<T> {
+  return Promise.resolve(uowStorage.run(uow, callback));
+}
+
+/**
+ * Type helper that enforces DatabaseRequestThisContext on all functions in a service object
+ */
+type WithDatabaseThis<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (this: DatabaseRequestThisContext, ...args: A) => R
+    : T[K] extends Record<string, unknown>
+      ? WithDatabaseThis<T[K]>
+      : T[K];
+};
+
+// Import types from fragno package
+import type {
+  FragmentDefinition,
+  RouteHandler,
+  FragnoPublicConfig,
+  RequestInputContext,
+  RequestOutputContext,
+} from "@fragno-dev/core";
+
+export { bindServicesToContext, type BoundServices };
+
+/**
+ * Route handler type for database fragments with access to Unit of Work.
+ */
+export type DatabaseRouteHandler = (
+  this: DatabaseRequestThisContext,
+  inputContext: RequestInputContext,
+  outputContext: RequestOutputContext,
+) => Promise<Response>;
 
 /**
  * Extended FragnoPublicConfig that includes a database adapter.
@@ -25,8 +97,20 @@ export class DatabaseFragmentBuilder<
   const TSchema extends AnySchema,
   const TConfig,
   const TDeps = {},
-  const TServices extends Record<string, unknown> = {},
+  const TServices = {},
+  const TUsedServices = {},
+  const TProvidedServices = {},
 > {
+  // Type-only property to expose type parameters for better inference
+  readonly $types!: {
+    schema: TSchema;
+    config: TConfig;
+    deps: TDeps;
+    services: TServices;
+    usedServices: TUsedServices;
+    providedServices: TProvidedServices;
+  };
+
   #name: string;
   #schema?: TSchema;
   #namespace?: string;
@@ -40,9 +124,14 @@ export class DatabaseFragmentBuilder<
     context: {
       config: TConfig;
       fragnoConfig: FragnoPublicConfig;
-      deps: TDeps;
+      deps: TDeps & TUsedServices;
+      defineService: <T extends Record<string, unknown>>(
+        services: WithDatabaseThis<T>,
+      ) => WithDatabaseThis<T>;
     } & DatabaseFragmentContext<TSchema>,
   ) => TServices;
+  #usedServices?: Record<string, { name: string; required: boolean }>;
+  #providedServices?: Record<string, unknown>;
 
   constructor(options: {
     name: string;
@@ -58,27 +147,43 @@ export class DatabaseFragmentBuilder<
       context: {
         config: TConfig;
         fragnoConfig: FragnoPublicConfig;
-        deps: TDeps;
+        deps: TDeps & TUsedServices;
+        defineService: <T extends Record<string, unknown>>(
+          services: WithDatabaseThis<T>,
+        ) => WithDatabaseThis<T>;
       } & DatabaseFragmentContext<TSchema>,
     ) => TServices;
+    usedServices?: Record<string, { name: string; required: boolean }>;
+    providedServices?: Record<string, unknown>;
   }) {
     this.#name = options.name;
     this.#schema = options.schema;
     this.#namespace = options.namespace;
     this.#dependencies = options.dependencies;
     this.#services = options.services;
+    this.#usedServices = options.usedServices;
+    this.#providedServices = options.providedServices;
   }
 
   get $requiredOptions(): FragnoPublicConfigWithDatabase {
     throw new Error("Type only method. Do not call.");
   }
 
-  get definition(): FragmentDefinition<TConfig, TDeps, TServices> {
+  get definition(): FragmentDefinition<
+    TConfig,
+    TDeps,
+    BoundServices<TServices>,
+    { databaseSchema?: TSchema; databaseNamespace: string },
+    BoundServices<TUsedServices>,
+    BoundServices<TProvidedServices>,
+    DatabaseRequestThisContext
+  > {
     const schema = this.#schema;
     const namespace = this.#namespace ?? "";
     const name = this.#name;
     const dependencies = this.#dependencies;
     const services = this.#services;
+    const providedServices = this.#providedServices;
 
     return {
       name,
@@ -86,16 +191,80 @@ export class DatabaseFragmentBuilder<
         const dbContext = this.#createDatabaseContext(options, schema, namespace, name);
         return dependencies?.({ config, fragnoConfig: options, ...dbContext }) ?? ({} as TDeps);
       },
-      services: (config: TConfig, options: FragnoPublicConfig, deps: TDeps) => {
+      services: (
+        config: TConfig,
+        options: FragnoPublicConfig,
+        deps: TDeps & BoundServices<TUsedServices>,
+      ) => {
         const dbContext = this.#createDatabaseContext(options, schema, namespace, name);
-        return (
-          services?.({ config, fragnoConfig: options, deps, ...dbContext }) ?? ({} as TServices)
-        );
+        // Cast deps back to raw type for internal services function.
+        // This is safe because:
+        // 1. deps are already bound (their 'this' parameters are stripped)
+        // 2. The services function expects raw types but only uses the public API
+        // 3. BoundServices<T> has the same runtime shape as T (just without 'this')
+
+        // defineService provides typing for service functions
+        // It expects the input to already have proper 'this' types on functions
+        const defineService = <T extends Record<string, unknown>>(
+          services: WithDatabaseThis<T>,
+        ): WithDatabaseThis<T> => services;
+
+        const rawServices =
+          services?.({
+            config,
+            fragnoConfig: options,
+            deps: deps as TDeps & TUsedServices,
+            defineService,
+            ...dbContext,
+          }) ?? ({} as TServices);
+
+        // Bind all service methods to serviceContext
+        return bindServicesToContext(
+          rawServices as Record<string, unknown>,
+        ) as BoundServices<TServices>;
       },
       additionalContext: {
         databaseSchema: schema,
         databaseNamespace: namespace,
       },
+      createHandlerWrapper: schema
+        ? (options: FragnoPublicConfig) => {
+            const dbContext = this.#createDatabaseContext(options, schema, namespace, name);
+            const { orm } = dbContext;
+
+            // Return handler wrapper function
+            return (handler: DatabaseRouteHandler): RouteHandler => {
+              return async (inputContext, outputContext) => {
+                // Create UOW for this request
+                const uow = orm.createUnitOfWork();
+
+                // Execute handler within AsyncLocalStorage context
+                return withUnitOfWork(uow, async () => {
+                  // Bind handler to serviceContext so it has access to getUnitOfWork via 'this'
+                  const boundHandler = handler.bind(serviceContext);
+                  return boundHandler(inputContext, outputContext);
+                });
+              };
+            };
+          }
+        : undefined,
+      usedServices: this.#usedServices as
+        | {
+            [K in keyof TUsedServices]: { name: string; required: boolean };
+          }
+        | undefined,
+      // Pass providedServices as-is - let fragment-instantiation.ts handle resolution
+      // The factory functions will be called by createFragment
+      providedServices: providedServices as
+        | {
+            [K in keyof BoundServices<TProvidedServices>]: BoundServices<TProvidedServices>[K];
+          }
+        | ((
+            config: TConfig,
+            options: FragnoPublicConfig,
+            deps: TDeps & BoundServices<TUsedServices>,
+          ) => BoundServices<TProvidedServices>)
+        | undefined,
     };
   }
 
@@ -128,8 +297,22 @@ export class DatabaseFragmentBuilder<
   withDatabase<TNewSchema extends AnySchema>(
     schema: TNewSchema,
     namespace?: string,
-  ): DatabaseFragmentBuilder<TNewSchema, TConfig, TDeps, TServices> {
-    return new DatabaseFragmentBuilder<TNewSchema, TConfig, TDeps, TServices>({
+  ): DatabaseFragmentBuilder<
+    TNewSchema,
+    TConfig,
+    TDeps,
+    TServices,
+    TUsedServices,
+    TProvidedServices
+  > {
+    return new DatabaseFragmentBuilder<
+      TNewSchema,
+      TConfig,
+      TDeps,
+      TServices,
+      TUsedServices,
+      TProvidedServices
+    >({
       name: this.#name,
       schema,
       namespace: namespace ?? this.#name + "-db",
@@ -146,10 +329,15 @@ export class DatabaseFragmentBuilder<
             context: {
               config: TConfig;
               fragnoConfig: FragnoPublicConfig;
-              deps: TDeps;
+              deps: TDeps & TUsedServices;
+              defineService: <T extends Record<string, unknown>>(
+                services: WithDatabaseThis<T>,
+              ) => WithDatabaseThis<T>;
             } & DatabaseFragmentContext<TNewSchema>,
           ) => TServices)
         | undefined,
+      usedServices: this.#usedServices,
+      providedServices: this.#providedServices,
     });
   }
 
@@ -160,39 +348,380 @@ export class DatabaseFragmentBuilder<
         fragnoConfig: FragnoPublicConfig;
       } & DatabaseFragmentContext<TSchema>,
     ) => TNewDeps,
-  ): DatabaseFragmentBuilder<TSchema, TConfig, TNewDeps, {}> {
-    return new DatabaseFragmentBuilder<TSchema, TConfig, TNewDeps, {}>({
+  ): DatabaseFragmentBuilder<TSchema, TConfig, TNewDeps, {}, TUsedServices, TProvidedServices> {
+    return new DatabaseFragmentBuilder<
+      TSchema,
+      TConfig,
+      TNewDeps,
+      {},
+      TUsedServices,
+      TProvidedServices
+    >({
       name: this.#name,
       schema: this.#schema,
       namespace: this.#namespace,
       dependencies: fn,
       services: undefined,
+      usedServices: this.#usedServices,
+      providedServices: this.#providedServices,
     });
   }
 
-  withServices<TNewServices extends Record<string, unknown>>(
-    fn: (
-      context: {
-        config: TConfig;
-        fragnoConfig: FragnoPublicConfig;
-        deps: TDeps;
-      } & DatabaseFragmentContext<TSchema>,
-    ) => TNewServices,
-  ): DatabaseFragmentBuilder<TSchema, TConfig, TDeps, TNewServices> {
-    return new DatabaseFragmentBuilder<TSchema, TConfig, TDeps, TNewServices>({
+  /**
+   * Declare that this fragment uses a service.
+   * @param serviceName - The name of the service to use
+   * @param options - Optional configuration: { optional: boolean } (defaults to required)
+   */
+  usesService<TServiceName extends string, TService>(
+    serviceName: TServiceName,
+    options?: { optional?: false },
+  ): DatabaseFragmentBuilder<
+    TSchema,
+    TConfig,
+    TDeps,
+    TServices,
+    TUsedServices & { [K in TServiceName]: TService },
+    TProvidedServices
+  >;
+  usesService<TServiceName extends string, TService>(
+    serviceName: TServiceName,
+    options: { optional: true },
+  ): DatabaseFragmentBuilder<
+    TSchema,
+    TConfig,
+    TDeps,
+    TServices,
+    TUsedServices & { [K in TServiceName]: TService | undefined },
+    TProvidedServices
+  >;
+  usesService<TServiceName extends string, TService>(
+    serviceName: TServiceName,
+    options?: { optional?: boolean },
+  ): DatabaseFragmentBuilder<
+    TSchema,
+    TConfig,
+    TDeps,
+    TServices,
+    TUsedServices & { [K in TServiceName]: TService | TService | undefined },
+    TProvidedServices
+  > {
+    const isOptional = options?.optional ?? false;
+    return new DatabaseFragmentBuilder<
+      TSchema,
+      TConfig,
+      TDeps,
+      TServices,
+      TUsedServices & { [K in TServiceName]: TService | (TService | undefined) },
+      TProvidedServices
+    >({
       name: this.#name,
       schema: this.#schema,
       namespace: this.#namespace,
-      dependencies: this.#dependencies,
-      services: fn,
+      dependencies: this.#dependencies as unknown as
+        | ((
+            context: {
+              config: TConfig;
+              fragnoConfig: FragnoPublicConfig;
+            } & DatabaseFragmentContext<TSchema>,
+          ) => TDeps)
+        | undefined,
+      services: this.#services as unknown as
+        | ((
+            context: {
+              config: TConfig;
+              fragnoConfig: FragnoPublicConfig;
+              deps: TDeps &
+                (TUsedServices & { [K in TServiceName]: TService | (TService | undefined) });
+            } & DatabaseFragmentContext<TSchema>,
+          ) => TServices)
+        | undefined,
+      usedServices: {
+        ...this.#usedServices,
+        [serviceName]: { name: serviceName, required: !isOptional },
+      },
+      providedServices: this.#providedServices,
     });
   }
+
+  /**
+   * Define services for this fragment (unnamed).
+   * Functions in the service will have access to DatabaseRequestThisContext via `this` if using `defineService`.
+   *
+   * @example
+   * With `this` context:
+   * ```ts
+   * .providesService(({ defineService }) => defineService({
+   *   createUser: function(name: string) {
+   *     const uow = this.getUnitOfWork(mySchema);
+   *     return uow.create('user', { name });
+   *   }
+   * }))
+   * ```
+   *
+   * Without `this` context:
+   * ```ts
+   * .providesService(({ db }) => ({
+   *   createUser: async (name: string) => {
+   *     return db.create('user', { name });
+   *   }
+   * }))
+   * ```
+   */
+  providesService<TNewServices>(
+    fn: (context: {
+      config: TConfig;
+      fragnoConfig: FragnoPublicConfig;
+      deps: TDeps & TUsedServices;
+      db: AbstractQuery<TSchema>;
+      defineService: <T extends Record<string, unknown>>(
+        services: WithDatabaseThis<T>,
+      ) => WithDatabaseThis<T>;
+    }) => TNewServices,
+  ): DatabaseFragmentBuilder<
+    TSchema,
+    TConfig,
+    TDeps,
+    TNewServices,
+    TUsedServices,
+    TProvidedServices
+  >;
+
+  /**
+   * Provide a named service that other fragments can use.
+   * Functions in the service will have access to DatabaseRequestThisContext via `this` if using `defineService`.
+   * You can also pass a service object directly instead of a callback.
+   *
+   * @example
+   * With callback and `this` context:
+   * ```ts
+   * .providesService("myService", ({ defineService }) => defineService({
+   *   createUser: function(name: string) {
+   *     const uow = this.getUnitOfWork(mySchema);
+   *     return uow.create('user', { name });
+   *   }
+   * }))
+   * ```
+   *
+   * With callback, no `this` context:
+   * ```ts
+   * .providesService("myService", ({ db }) => ({
+   *   createUser: async (name: string) => {
+   *     return db.create('user', { name });
+   *   }
+   * }))
+   * ```
+   *
+   * With direct object:
+   * ```ts
+   * .providesService("myService", {
+   *   createUser: async (name: string) => { ... }
+   * })
+   * ```
+   */
+  providesService<TServiceName extends string, TService>(
+    serviceName: TServiceName,
+    fnOrService:
+      | ((context: {
+          config: TConfig;
+          fragnoConfig: FragnoPublicConfig;
+          deps: TDeps & TUsedServices;
+          db: AbstractQuery<TSchema>;
+          defineService: <T extends Record<string, unknown>>(
+            services: WithDatabaseThis<T>,
+          ) => WithDatabaseThis<T>;
+        }) => TService)
+      | TService,
+  ): DatabaseFragmentBuilder<
+    TSchema,
+    TConfig,
+    TDeps,
+    TServices,
+    TUsedServices,
+    TProvidedServices & { [K in TServiceName]: BoundServices<TService> }
+  >;
+
+  providesService<TServiceName extends string, TService>(
+    ...args:
+      | [
+          fn: (context: {
+            config: TConfig;
+            fragnoConfig: FragnoPublicConfig;
+            deps: TDeps & TUsedServices;
+            db: AbstractQuery<TSchema>;
+            defineService: <T extends Record<string, unknown>>(
+              services: WithDatabaseThis<T>,
+            ) => WithDatabaseThis<T>;
+          }) => TService,
+        ]
+      | [
+          serviceName: TServiceName,
+          fnOrService:
+            | ((context: {
+                config: TConfig;
+                fragnoConfig: FragnoPublicConfig;
+                deps: TDeps & TUsedServices;
+                db: AbstractQuery<TSchema>;
+                defineService: <T extends Record<string, unknown>>(
+                  services: WithDatabaseThis<T>,
+                ) => WithDatabaseThis<T>;
+              }) => TService)
+            | TService,
+        ]
+  ):
+    | DatabaseFragmentBuilder<TSchema, TConfig, TDeps, TService, TUsedServices, TProvidedServices>
+    | DatabaseFragmentBuilder<
+        TSchema,
+        TConfig,
+        TDeps,
+        TServices,
+        TUsedServices,
+        TProvidedServices & { [K in TServiceName]: BoundServices<TService> }
+      > {
+    if (args.length === 1) {
+      // Unnamed service - replaces withServices
+      const [fn] = args;
+
+      // Create a callback that takes a single context object (matching #services signature)
+      // Note: We don't explicitly type the return to preserve the WithDatabaseThis wrapper
+      const servicesCallback = (
+        context: {
+          config: TConfig;
+          fragnoConfig: FragnoPublicConfig;
+          deps: TDeps & TUsedServices;
+        } & DatabaseFragmentContext<TSchema>,
+      ) => {
+        // defineService provides typing for service functions
+        // It expects the input to already have proper 'this' types on functions
+        const defineService = <T extends Record<string, unknown>>(
+          services: WithDatabaseThis<T>,
+        ): WithDatabaseThis<T> => services;
+
+        const services = fn({
+          config: context.config,
+          fragnoConfig: context.fragnoConfig,
+          deps: context.deps,
+          db: context.orm,
+          defineService,
+        });
+
+        // Return without casting to preserve the WithDatabaseThis wrapper
+        return services;
+      };
+
+      return new DatabaseFragmentBuilder<
+        TSchema,
+        TConfig,
+        TDeps,
+        TService,
+        TUsedServices,
+        TProvidedServices
+      >({
+        name: this.#name,
+        schema: this.#schema,
+        namespace: this.#namespace,
+        dependencies: this.#dependencies,
+        // Safe cast: servicesCallback returns WithDatabaseThis<TService> but we store it as TService.
+        // At runtime, bindServicesToContext will handle the 'this' binding properly.
+        services: servicesCallback as (
+          context: {
+            config: TConfig;
+            fragnoConfig: FragnoPublicConfig;
+            deps: TDeps & TUsedServices;
+            defineService: <T extends Record<string, unknown>>(
+              services: WithDatabaseThis<T>,
+            ) => WithDatabaseThis<T>;
+          } & DatabaseFragmentContext<TSchema>,
+        ) => TService,
+        usedServices: this.#usedServices,
+        providedServices: this.#providedServices,
+      });
+    } else {
+      // Named service
+      const [serviceName, fnOrService] = args;
+
+      // Create a callback that provides the full context
+      const createService = (
+        config: TConfig,
+        options: FragnoPublicConfig,
+        deps: TDeps & TUsedServices,
+      ): BoundServices<TService> => {
+        const dbContext = this.#createDatabaseContext(
+          options,
+          this.#schema,
+          this.#namespace ?? "",
+          this.#name,
+        );
+
+        // Check if fnOrService is a function or a direct object
+        let implementation: TService;
+        if (typeof fnOrService === "function") {
+          // It's a callback - call it with context
+          // defineService provides typing for service functions
+          // It expects the input to already have proper 'this' types on functions
+          const defineService = <T extends Record<string, unknown>>(
+            services: WithDatabaseThis<T>,
+          ): WithDatabaseThis<T> => services;
+
+          // Safe cast: we checked that fnOrService is a function
+          implementation = (
+            fnOrService as (context: {
+              config: TConfig;
+              fragnoConfig: FragnoPublicConfig;
+              deps: TDeps & TUsedServices;
+              db: AbstractQuery<TSchema>;
+              defineService: <T extends Record<string, unknown>>(
+                services: WithDatabaseThis<T>,
+              ) => WithDatabaseThis<T>;
+            }) => TService
+          )({
+            config,
+            fragnoConfig: options,
+            deps,
+            db: dbContext.orm,
+            defineService,
+          });
+        } else {
+          // It's a direct object
+          implementation = fnOrService;
+        }
+
+        // Bind the service implementation so methods have access to serviceContext
+        return bindServicesToContext(
+          implementation as Record<string, unknown>,
+        ) as BoundServices<TService>;
+      };
+
+      // We need to evaluate this immediately to store in providedServices
+      // For now, we'll create a placeholder that will be evaluated when fragment is instantiated
+      // Actually, we need to defer this until fragment instantiation
+      // Let's store a function that creates the service
+      return new DatabaseFragmentBuilder<
+        TSchema,
+        TConfig,
+        TDeps,
+        TServices,
+        TUsedServices,
+        TProvidedServices & { [K in TServiceName]: BoundServices<TService> }
+      >({
+        name: this.#name,
+        schema: this.#schema,
+        namespace: this.#namespace,
+        dependencies: this.#dependencies,
+        services: this.#services,
+        usedServices: this.#usedServices,
+        providedServices: {
+          ...this.#providedServices,
+          [serviceName]: createService,
+        } as Record<string, unknown>,
+      });
+    }
+  }
 }
 
 export function defineFragmentWithDatabase<TConfig = {}>(
   name: string,
-): DatabaseFragmentBuilder<never, TConfig, {}, {}> {
-  return new DatabaseFragmentBuilder<never, TConfig, {}, {}>({
+): DatabaseFragmentBuilder<never, TConfig, {}, {}, {}, {}> {
+  return new DatabaseFragmentBuilder<never, TConfig, {}, {}, {}, {}>({
     name,
   });
 }