@geekmidas/constructs 0.0.12 → 0.0.13

package/src/endpoints/Endpoint.ts

@@ -1,4 +1,4 @@
-import type { AuditableAction, Auditor, AuditStorage } from '@geekmidas/audit';
+import type { AuditStorage, AuditableAction, Auditor } from '@geekmidas/audit';
 import type {
   EventPublisher,
   ExtractPublisherMessage,
@@ -27,8 +27,8 @@ import type { OpenAPIV3_1 } from 'openapi-types';
 import { ConstructType } from '../Construct';
 import { Function, type FunctionHandler } from '../functions';
 import type { HttpMethod, LowerHttpMethod, RemoveUndefined } from '../types';
-import type { ActorExtractor, MappedAudit } from './audit';
 import type { Authorizer } from './Authorizer';
+import type { ActorExtractor, MappedAudit } from './audit';
 
 /**
  * Represents an HTTP endpoint that can handle requests with type-safe input/output validation,
@@ -71,16 +71,29 @@ export class Endpoint<
     string,
     unknown
   >,
+  TDatabase = undefined,
+  TDatabaseServiceName extends string = string,
 > extends Function<
   TInput,
   TServices,
   TLogger,
   OutSchema,
-  FunctionHandler<TInput, TServices, TLogger, OutSchema>,
   TEventPublisher,
   TEventPublisherServiceName,
   TAuditStorage,
-  TAuditStorageServiceName
+  TAuditStorageServiceName,
+  TDatabase,
+  TDatabaseServiceName,
+  TAuditAction,
+  FunctionHandler<
+    TInput,
+    TServices,
+    TLogger,
+    OutSchema,
+    TDatabase,
+    TAuditStorage,
+    TAuditAction
+  >
 > {
   operationId?: string;
   /** The route path pattern with parameter placeholders */
@@ -108,13 +121,18 @@ export class Endpoint<
   public actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
   /** Declarative audit definitions */
   public audits: MappedAudit<TAuditAction, OutSchema>[] = [];
+  /** Database service for this endpoint */
+  public databaseService?: Service<TDatabaseServiceName, TDatabase>;
   /** The endpoint handler function */
   private endpointFn!: EndpointHandler<
     TInput,
     TServices,
     TLogger,
     OutSchema,
-    TSession
+    TSession,
+    TDatabase,
+    TAuditStorage,
+    TAuditAction
   >;
 
   /**
@@ -321,7 +339,15 @@ export class Endpoint<
   }
 
   handler = (
-    ctx: EndpointContext<TInput, TServices, TLogger, TSession>,
+    ctx: EndpointContext<
+      TInput,
+      TServices,
+      TLogger,
+      TSession,
+      TAuditAction,
+      TDatabase,
+      TAuditStorage
+    >,
     response: ResponseBuilder,
   ): OutSchema extends StandardSchemaV1
     ?
@@ -339,18 +365,28 @@ export class Endpoint<
       response.header(key, value);
     }
 
-    return this.endpointFn(
-      {
-        ...this.refineInput(ctx),
-        services: ctx.services,
-        logger: ctx.logger,
-        header: ctx.header,
-        cookie: ctx.cookie,
-        session: ctx.session,
-        auditor: ctx.auditor,
-      } as EndpointContext<TInput, TServices, TLogger, TSession>,
-      response,
-    );
+    // Build context object, conditionally including auditor and db
+    const handlerCtx = {
+      ...this.refineInput(ctx),
+      services: ctx.services,
+      logger: ctx.logger,
+      header: ctx.header,
+      cookie: ctx.cookie,
+      session: ctx.session,
+      // These are conditionally present based on configuration
+      ...('auditor' in ctx && { auditor: ctx.auditor }),
+      ...('db' in ctx && { db: ctx.db }),
+    } as EndpointContext<
+      TInput,
+      TServices,
+      TLogger,
+      TSession,
+      TAuditAction,
+      TDatabase,
+      TAuditStorage
+    >;
+
+    return this.endpointFn(handlerCtx, response);
   };
 
   /**
@@ -556,6 +592,7 @@ export class Endpoint<
     auditorStorageService,
     actorExtractor,
     audits,
+    databaseService,
   }: EndpointOptions<
     TRoute,
     TMethod,
@@ -569,7 +606,9 @@ export class Endpoint<
     TEventPublisherServiceName,
     TAuditStorage,
     TAuditStorageServiceName,
-    TAuditAction
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   >) {
     super(
       fn as unknown as FunctionHandler<TInput, TServices, TLogger, OutSchema>,
@@ -615,6 +654,10 @@ export class Endpoint<
     if (audits) {
       this.audits = audits;
     }
+
+    if (databaseService) {
+      this.databaseService = databaseService;
+    }
   }
 }
 
@@ -672,13 +715,24 @@ export interface EndpointOptions<
     string,
     unknown
   >,
+  TDatabase = undefined,
+  TDatabaseServiceName extends string = string,
 > {
   /** The route path with parameter placeholders */
   route: TRoute;
   /** The HTTP method for this endpoint */
   method: TMethod;
   /** The handler function that implements the endpoint logic */
-  fn: EndpointHandler<TInput, TServices, TLogger, TOutput, TSession>;
+  fn: EndpointHandler<
+    TInput,
+    TServices,
+    TLogger,
+    TOutput,
+    TSession,
+    TDatabase,
+    TAuditStorage,
+    TAuditAction
+  >;
   /** Optional authorization check function */
   authorize: AuthorizeFn<TServices, TLogger, TSession> | undefined;
   /** Optional description for documentation */
@@ -719,6 +773,8 @@ export interface EndpointOptions<
   actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
   /** Declarative audit definitions */
   audits?: MappedAudit<TAuditAction, OutSchema>[];
+  /** Database service for this endpoint */
+  databaseService?: Service<TDatabaseServiceName, TDatabase>;
 }
 
 /**
@@ -968,6 +1024,62 @@ export class ResponseBuilder {
   }
 }
 
+/**
+ * Base context properties that are always available
+ */
+type BaseEndpointContext<
+  TServices extends Service[] = [],
+  TLogger extends Logger = Logger,
+  TSession = unknown,
+> = {
+  /** Injected service instances */
+  services: ServiceRecord<TServices>;
+  /** Logger instance for this request */
+  logger: TLogger;
+  /** Function to retrieve request headers */
+  header: HeaderFn;
+  /** Function to retrieve request cookies */
+  cookie: CookieFn;
+  /** Session data extracted by getSession */
+  session: TSession;
+};
+
+/**
+ * Conditional auditor context - only present when audit storage is configured
+ */
+type AuditorContext<
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+  TAuditStorage = undefined,
+> = TAuditStorage extends undefined
+  ? {}
+  : {
+      /**
+       * Auditor instance for recording audit events.
+       * Only present when audit storage is configured on the endpoint.
+       * When a transactional database is used for audit storage,
+       * the auditor is pre-configured with the transaction context.
+       */
+      auditor: Auditor<TAuditAction>;
+    };
+
+/**
+ * Conditional database context - only present when database service is configured
+ */
+type DatabaseContext<TDatabase = undefined> = TDatabase extends undefined
+  ? {}
+  : {
+      /**
+       * Database instance for this request.
+       * When audit storage is configured and uses the same database,
+       * this will be the transaction for ACID compliance.
+       * Otherwise, it's the raw database connection.
+       */
+      db: TDatabase;
+    };
+
 /**
  * The execution context provided to endpoint handlers.
  * Contains all parsed input data, services, logger, headers, cookies, and session.
@@ -976,6 +1088,9 @@ export class ResponseBuilder {
  * @template TServices - Available service dependencies
  * @template TLogger - Logger type
  * @template TSession - Session data type
+ * @template TAuditAction - Audit action types (when auditor is configured)
+ * @template TDatabase - Database type (when database service is configured)
+ * @template TAuditStorage - Audit storage type (determines if auditor is present)
  */
 export type EndpointContext<
   Input extends EndpointSchemas | undefined = undefined,
@@ -986,25 +1101,12 @@ export type EndpointContext<
     string,
     unknown
   >,
-> = {
-  /** Injected service instances */
-  services: ServiceRecord<TServices>;
-  /** Logger instance for this request */
-  logger: TLogger;
-  /** Function to retrieve request headers */
-  header: HeaderFn;
-  /** Function to retrieve request cookies */
-  cookie: CookieFn;
-  /** Session data extracted by getSession */
-  session: TSession;
-  /**
-   * Auditor instance for recording audit events.
-   * Only present when audit storage is configured on the endpoint.
-   * When a transactional database is used for audit storage,
-   * the auditor is pre-configured with the transaction context.
-   */
-  auditor?: Auditor<TAuditAction>;
-} & InferComposableStandardSchema<Input>;
+  TDatabase = undefined,
+  TAuditStorage = undefined,
+> = BaseEndpointContext<TServices, TLogger, TSession> &
+  InferComposableStandardSchema<Input> &
+  AuditorContext<TAuditAction, TAuditStorage> &
+  DatabaseContext<TDatabase>;
 
 /**
  * Handler function type for endpoint implementations.
@@ -1041,8 +1143,22 @@ export type EndpointHandler<
   TLogger extends Logger = Logger,
   OutSchema extends StandardSchemaV1 | undefined = undefined,
   TSession = unknown,
+  TDatabase = undefined,
+  TAuditStorage = undefined,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
 > = (
-  ctx: EndpointContext<TInput, TServices, TLogger, TSession>,
+  ctx: EndpointContext<
+    TInput,
+    TServices,
+    TLogger,
+    TSession,
+    TAuditAction,
+    TDatabase,
+    TAuditStorage
+  >,
   response: ResponseBuilder,
 ) => OutSchema extends StandardSchemaV1
   ?

package/src/endpoints/EndpointBuilder.ts

@@ -1,4 +1,4 @@
-import type { AuditableAction, AuditStorage } from '@geekmidas/audit';
+import type { AuditStorage, AuditableAction } from '@geekmidas/audit';
 import type { EventPublisher, MappedEvent } from '@geekmidas/events';
 import type { Logger } from '@geekmidas/logger';
 import type { RateLimitConfig } from '@geekmidas/rate-limit';
@@ -8,7 +8,6 @@ import uniqBy from 'lodash.uniqby';
 import { ConstructType } from '../Construct';
 import { BaseFunctionBuilder } from '../functions';
 import type { HttpMethod } from '../types';
-import type { ActorExtractor, MappedAudit } from './audit';
 import type { Authorizer } from './Authorizer';
 import { Endpoint, type EndpointSchemas } from './Endpoint';
 import type {
@@ -17,6 +16,7 @@ import type {
   SessionFn,
   SuccessStatus,
 } from './Endpoint';
+import type { ActorExtractor, MappedAudit } from './audit';
 
 export class EndpointBuilder<
   TRoute extends string,
@@ -35,6 +35,8 @@ export class EndpointBuilder<
     string,
     unknown
   >,
+  TDatabase = undefined,
+  TDatabaseServiceName extends string = string,
 > extends BaseFunctionBuilder<
   TInput,
   OutSchema,
@@ -57,6 +59,7 @@ export class EndpointBuilder<
   _authorizerName?: TAuthorizers[number];
   _actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
   _audits: MappedAudit<TAuditAction, OutSchema>[] = [];
+  _databaseService?: Service<TDatabaseServiceName, TDatabase>;
 
   constructor(
     readonly route: TRoute,
@@ -237,7 +240,10 @@ export class EndpointBuilder<
     TEventPublisherServiceName,
     TAuthorizers,
     TAuditStorage,
-    TAuditStorageServiceName
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     // Special case: 'none' explicitly marks endpoint as having no authorizer
     if (name === 'none') {
@@ -250,7 +256,9 @@ export class EndpointBuilder<
       (a) => a.name === name,
     );
     if (!authorizerExists && this._availableAuthorizers.length > 0) {
-      const available = this._availableAuthorizers.map((a) => a.name).join(', ');
+      const available = this._availableAuthorizers
+        .map((a) => a.name)
+        .join(', ');
       throw new Error(
         `Authorizer "${name as string}" not found in available authorizers: ${available}`,
       );
@@ -273,7 +281,10 @@ export class EndpointBuilder<
     TEventPublisherServiceName,
     TAuthorizers,
     TAuditStorage,
-    TAuditStorageServiceName
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this._services = uniqBy(
       [...this._services, ...services],
@@ -292,7 +303,10 @@ export class EndpointBuilder<
       TEventPublisherServiceName,
       TAuthorizers,
       TAuditStorage,
-      TAuditStorageServiceName
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
     >;
   }
 
@@ -310,7 +324,10 @@ export class EndpointBuilder<
     TEventPublisherServiceName,
     TAuthorizers,
     TAuditStorage,
-    TAuditStorageServiceName
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this._logger = logger as unknown as TLogger;
 
@@ -326,7 +343,10 @@ export class EndpointBuilder<
       TEventPublisherServiceName,
       TAuthorizers,
       TAuditStorage,
-      TAuditStorageServiceName
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
     >;
   }
 
@@ -344,7 +364,10 @@ export class EndpointBuilder<
     TEventPublisherServiceName,
     TAuthorizers,
     TAuditStorage,
-    TAuditStorageServiceName
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this.outputSchema = schema as unknown as OutSchema;
 
@@ -360,7 +383,10 @@ export class EndpointBuilder<
       TEventPublisherServiceName,
       TAuthorizers,
       TAuditStorage,
-      TAuditStorageServiceName
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
     >;
   }
 
@@ -383,7 +409,9 @@ export class EndpointBuilder<
     TAuthorizers,
     T,
     TName,
-    TAuditAction
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this._auditorStorage = storage as unknown as Service<
       TAuditStorageServiceName,
@@ -403,7 +431,9 @@ export class EndpointBuilder<
       TAuthorizers,
       T,
       TName,
-      TAuditAction
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
     >;
   }
 
@@ -426,7 +456,9 @@ export class EndpointBuilder<
     TAuthorizers,
     TAuditStorage,
     TAuditStorageServiceName,
-    TAuditAction
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this._actorExtractor = extractor;
     return this;
@@ -464,7 +496,9 @@ export class EndpointBuilder<
     TAuthorizers,
     TAuditStorage,
     TAuditStorageServiceName,
-    T
+    T,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this._audits = audits as unknown as MappedAudit<TAuditAction, OutSchema>[];
     return this as unknown as EndpointBuilder<
@@ -480,7 +514,67 @@ export class EndpointBuilder<
       TAuthorizers,
       TAuditStorage,
       TAuditStorageServiceName,
-      T
+      T,
+      TDatabase,
+      TDatabaseServiceName
+    >;
+  }
+
+  /**
+   * Set the database service for this endpoint.
+   * The database will be available in the handler context as `db`.
+   * When audit storage is configured and uses the same database,
+   * `db` will automatically be the transaction for ACID compliance.
+   *
+   * @example
+   * ```typescript
+   * .database(databaseService)
+   * .handle(async ({ db }) => {
+   *   // db is the raw database or transaction (when auditor uses same db)
+   *   return await db.selectFrom('users').selectAll().execute();
+   * })
+   * ```
+   */
+  database<T, TName extends string>(
+    service: Service<TName, T>,
+  ): EndpointBuilder<
+    TRoute,
+    TMethod,
+    TInput,
+    TServices,
+    TLogger,
+    OutSchema,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    T,
+    TName
+  > {
+    this._databaseService = service as unknown as Service<
+      TDatabaseServiceName,
+      TDatabase
+    >;
+
+    return this as unknown as EndpointBuilder<
+      TRoute,
+      TMethod,
+      TInput,
+      TServices,
+      TLogger,
+      OutSchema,
+      TSession,
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      T,
+      TName
     >;
   }
 
@@ -492,7 +586,16 @@ export class EndpointBuilder<
   }
 
   handle(
-    fn: EndpointHandler<TInput, TServices, TLogger, OutSchema, TSession>,
+    fn: EndpointHandler<
+      TInput,
+      TServices,
+      TLogger,
+      OutSchema,
+      TSession,
+      TDatabase,
+      TAuditStorage,
+      TAuditAction
+    >,
   ): Endpoint<
     TRoute,
     TMethod,
@@ -505,7 +608,9 @@ export class EndpointBuilder<
     TEventPublisherServiceName,
     TAuditStorage,
     TAuditStorageServiceName,
-    TAuditAction
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     // Find authorizer metadata if name is set
     const authorizer = this._authorizerName
@@ -534,6 +639,7 @@ export class EndpointBuilder<
       auditorStorageService: this._auditorStorage,
       actorExtractor: this._actorExtractor,
       audits: this._audits,
+      databaseService: this._databaseService,
     });
   }
 }

package/src/endpoints/EndpointFactory.ts

@@ -264,7 +264,11 @@ export class EndpointFactory<
       >,
       defaultLogger: logger,
       defaultSessionExtractor: this
-        .defaultSessionExtractor as unknown as SessionFn<TServices, L, TSession>,
+        .defaultSessionExtractor as unknown as SessionFn<
+        TServices,
+        L,
+        TSession
+      >,
       defaultEventPublisher: this.defaultEventPublisher,
       availableAuthorizers: this.availableAuthorizers,
       defaultAuthorizerName: this.defaultAuthorizerName,

package/src/endpoints/HonoEndpointAdaptor.ts

@@ -1,4 +1,4 @@
-import type { AuditableAction, AuditStorage } from '@geekmidas/audit';
+import type { AuditStorage, AuditableAction } from '@geekmidas/audit';
 import type { EnvironmentParser } from '@geekmidas/envkit';
 import type { EventPublisher } from '@geekmidas/events';
 import type { Logger } from '@geekmidas/logger';
@@ -20,7 +20,6 @@ import { getEndpointsFromRoutes } from './helpers';
 import { parseHonoQuery } from './parseHonoQuery';
 
 import { wrapError } from '@geekmidas/errors';
-import type { InferStandardSchema } from '@geekmidas/schema';
 import {
   type Service,
   ServiceDiscovery,
@@ -67,6 +66,8 @@ export class HonoEndpoint<
     string,
     unknown
   >,
+  TDatabase = undefined,
+  TDatabaseServiceName extends string = string,
 > {
   constructor(
     private readonly endpoint: Endpoint<
@@ -81,7 +82,9 @@ export class HonoEndpoint<
       TEventPublisherServiceName,
       TAuditStorage,
       TAuditStorageServiceName,
-      TAuditAction
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
     >,
   ) {}
 
@@ -241,6 +244,8 @@ export class HonoEndpoint<
       string,
       unknown
     >,
+    TDatabase = undefined,
+    TDatabaseServiceName extends string = string,
   >(
     endpoint: Endpoint<
       TRoute,
@@ -254,7 +259,9 @@ export class HonoEndpoint<
       TEventPublisherServiceName,
       TAuditStorage,
       TAuditStorageServiceName,
-      TAuditAction
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
     >,
     serviceDiscovery: ServiceDiscovery<ServiceRecord<TServices>, TLogger>,
     app: Hono,
@@ -356,10 +363,29 @@ export class HonoEndpoint<
             logger.warn('No auditor storage service available');
           }
 
+          // Resolve database service if configured
+          const rawDb = endpoint.databaseService
+            ? await serviceDiscovery
+                .register([endpoint.databaseService])
+                .then(
+                  (s) =>
+                    s[endpoint.databaseService!.serviceName as keyof typeof s],
+                )
+            : undefined;
+
           // Execute handler with automatic audit transaction support
           const result = await executeWithAuditTransaction(
             auditContext,
             async (auditor) => {
+              // Use audit transaction as db only if the storage uses the same database service
+              const sameDatabase =
+                auditContext?.storage?.databaseServiceName &&
+                auditContext.storage.databaseServiceName ===
+                  endpoint.databaseService?.serviceName;
+              const db = sameDatabase
+                ? (auditor?.getTransaction?.() ?? rawDb)
+                : rawDb;
+
               const responseBuilder = new ResponseBuilder();
               const response = await endpoint.handler(
                 {
@@ -372,11 +398,15 @@ export class HonoEndpoint<
                   header,
                   cookie,
                   auditor,
+                  db,
                 } as unknown as EndpointContext<
                   TInput,
                   TServices,
                   TLogger,
-                  TSession
+                  TSession,
+                  TAuditAction,
+                  TDatabase,
+                  TAuditStorage
                 >,
                 responseBuilder,
               );