@geekmidas/constructs 0.0.1

package/dist/Endpoint-C7z9YJHK.d.cts

@@ -0,0 +1,405 @@
+import { HttpMethod, LowerHttpMethod, RemoveUndefined } from "./types-Bp9ysFXd.cjs";
+import { Function, FunctionHandler } from "./Function-BP58p9Mp.cjs";
+import { EventPublisher, ExtractPublisherMessage, MappedEvent } from "@geekmidas/events";
+import { Logger } from "@geekmidas/logger";
+import { Service, ServiceRecord } from "@geekmidas/services";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { OpenAPIV3_1 } from "openapi-types";
+import { InferComposableStandardSchema, InferStandardSchema } from "@geekmidas/schema";
+import { RateLimitConfig } from "@geekmidas/rate-limit";
+import { ComponentCollector, OpenApiSchemaOptions } from "@geekmidas/schema/openapi";
+
+//#region src/endpoints/Endpoint.d.ts
+
+/**
+ * Represents an HTTP endpoint that can handle requests with type-safe input/output validation,
+ * dependency injection, session management, and authorization.
+ *
+ * @template TRoute - The route path string with parameter placeholders (e.g., '/users/:id')
+ * @template TMethod - The HTTP method (GET, POST, PUT, DELETE, PATCH)
+ * @template TInput - The input schema definition for body, query, and path parameters
+ * @template OutSchema - The output schema for response validation
+ * @template TServices - Array of service dependencies to inject
+ * @template TLogger - The logger instance type
+ * @template TSession - The session data type
+ *
+ * @extends Function - Base function construct for handler execution
+ *
+ * @example
+ * ```typescript
+ * const endpoint = new Endpoint({
+ *   route: '/users/:id',
+ *   method: 'GET',
+ *   input: { params: userIdSchema },
+ *   output: userSchema,
+ *   fn: async ({ params }) => getUserById(params.id)
+ * });
+ * ```
+ */
+declare class Endpoint<TRoute extends string, TMethod extends HttpMethod, TInput extends EndpointSchemas = {}, OutSchema extends StandardSchemaV1 | undefined = undefined, TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown, TEventPublisher extends EventPublisher<any> | undefined = undefined, TEventPublisherServiceName extends string = string> extends Function<TInput, TServices, TLogger, OutSchema, FunctionHandler<TInput, TServices, TLogger, OutSchema>, TEventPublisher, TEventPublisherServiceName> {
+  operationId?: string;
+  /** The route path pattern with parameter placeholders */
+  route: TRoute;
+  /** The HTTP method for this endpoint */
+  method: TMethod;
+  /** Optional description for OpenAPI documentation */
+  description?: string;
+  /** Optional tags for OpenAPI documentation */
+  tags?: string[];
+  /** The HTTP success status code to return (default: 200) */
+  readonly status: SuccessStatus;
+  /** Function to extract session data from the request context */
+  getSession: SessionFn<TServices, TLogger, TSession>;
+  /** Function to determine if the request is authorized */
+  authorize: AuthorizeFn<TServices, TLogger, TSession>;
+  /** Optional rate limiting configuration */
+  rateLimit?: RateLimitConfig;
+  /**
+   * Builds a complete OpenAPI 3.1 schema from an array of endpoints.
+   *
+   * @param endpoints - Array of endpoint instances to document
+   * @param options - Optional configuration for OpenAPI generation
+   * @returns OpenAPI 3.1 specification object
+   *
+   * @example
+   * ```typescript
+   * const schema = await Endpoint.buildOpenApiSchema([
+   *   getUserEndpoint,
+   *   createUserEndpoint
+   * ], {
+   *   title: 'User API',
+   *   version: '1.0.0'
+   * });
+   * ```
+   */
+  static buildOpenApiSchema(endpoints: Endpoint<any, any, any, any, any, any>[], options?: OpenApiSchemaOptions): Promise<OpenAPIV3_1.Document<{}>>;
+  /**
+   * Gets the full path including HTTP method and route.
+   * @returns Formatted string like 'GET /users/{id}'
+   */
+  get fullPath(): `${TMethod} ${ConvertRouteParams<TRoute>}`;
+  /**
+   * Parses and validates input data for a specific input type (body, query, params).
+   *
+   * @param input - The raw input data to validate
+   * @param key - The input type key ('body', 'query', or 'params')
+   * @returns The validated input data for the specified key
+   * @throws {UnprocessableEntityError} When validation fails
+   */
+  parseInput<K extends keyof TInput>(input: unknown, key: K): Promise<InferComposableStandardSchema<TInput[K]>>;
+  /**
+   * Parses and validates the request body against the body schema.
+   *
+   * @param body - The raw request body to validate
+   * @returns The validated body data
+   * @throws {UnprocessableEntityError} When body validation fails
+   */
+  parseBody(body: unknown): Promise<InferStandardSchema<TInput['body']>>;
+  static isSuccessStatus(status: number): boolean;
+  /**
+   * Creates a case-insensitive header lookup function from a headers object.
+   *
+   * @param headers - Object containing header key-value pairs
+   * @returns Function to retrieve header values by case-insensitive key
+   *
+   * @example
+   * ```typescript
+   * const headerFn = Endpoint.createHeaders({ 'Content-Type': 'application/json' });
+   * headerFn('content-type'); // Returns 'application/json'
+   * ```
+   */
+  static createHeaders(headers: Record<string, string>): HeaderFn;
+  /**
+   * Extracts and refines input data from the endpoint context.
+   *
+   * @param ctx - The endpoint execution context
+   * @returns Object containing only the input data (body, query, params)
+   * @internal
+   */
+  refineInput(ctx: EndpointContext<TInput, TServices, TLogger, TSession>): InferComposableStandardSchema<TInput>;
+  handler: EndpointHandler<TInput, TServices, TLogger, OutSchema, TSession>;
+  /**
+   * Type guard to check if an object is an Endpoint instance.
+   *
+   * @param obj - The object to check
+   * @returns True if the object is an Endpoint
+   */
+  static isEndpoint(obj: any): obj is Endpoint<any, any, any, any>;
+  /**
+   * Converts Express-style route params to OpenAPI format.
+   * @returns Route with ':param' converted to '{param}'
+   * @internal
+   */
+  get _path(): ConvertRouteParams<TRoute>;
+  /**
+   * Generates OpenAPI 3.1 schema for this endpoint.
+   *
+   * @returns OpenAPI route definition with operation details
+   */
+  toOpenApi3Route(componentCollector?: ComponentCollector): Promise<EndpointOpenApiSchema<TRoute, TMethod>>;
+  /**
+   * Creates a new Endpoint instance.
+   *
+   * @param options - Configuration options for the endpoint
+   * @param options.fn - The handler function to execute
+   * @param options.method - HTTP method
+   * @param options.route - Route path with parameter placeholders
+   * @param options.description - Optional description for documentation
+   * @param options.input - Input schemas for validation
+   * @param options.logger - Logger instance
+   * @param options.output - Output schema for response validation
+   * @param options.services - Service dependencies
+   * @param options.timeout - Execution timeout in milliseconds
+   * @param options.getSession - Session extraction function
+   * @param options.authorize - Authorization check function
+   * @param options.status - Success HTTP status code (default: 200)
+   */
+  constructor({
+    fn,
+    method,
+    route,
+    description,
+    tags,
+    input,
+    logger,
+    output: outputSchema,
+    services,
+    timeout,
+    getSession,
+    authorize,
+    rateLimit,
+    status,
+    publisherService,
+    events
+  }: EndpointOptions<TRoute, TMethod, TInput, OutSchema, TServices, TLogger, TSession, OutSchema, TEventPublisher, TEventPublisherServiceName>);
+}
+/**
+ * Defines the input schema structure for an endpoint.
+ *
+ * @template TBody - Schema for request body validation
+ * @template TSearch - Schema for query string validation
+ * @template TParams - Schema for URL path parameters validation
+ *
+ * @example
+ * ```typescript
+ * type UserInput = EndpointInput<
+ *   typeof createUserBodySchema,
+ *   typeof userQuerySchema,
+ *   typeof userParamsSchema
+ * >;
+ * ```
+ */
+type EndpointInput<TBody extends StandardSchemaV1 | undefined = undefined, TSearch extends StandardSchemaV1 | undefined = undefined, TParams extends StandardSchemaV1 | undefined = undefined> = RemoveUndefined<{
+  body: TBody;
+  search: TSearch;
+  params: TParams;
+}>;
+/**
+ * Configuration options for creating an Endpoint instance.
+ *
+ * @template TRoute - The route path string
+ * @template TMethod - The HTTP method
+ * @template TInput - Input schema definitions
+ * @template TOutput - Output schema definition
+ * @template TServices - Service dependencies array
+ * @template TLogger - Logger type
+ * @template TSession - Session data type
+ */
+interface EndpointOptions<TRoute extends string, TMethod extends HttpMethod, TInput extends EndpointSchemas = {}, TOutput extends StandardSchemaV1 | undefined = undefined, TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown, OutSchema extends StandardSchemaV1 | undefined = undefined, TEventPublisher extends EventPublisher<any> | undefined = undefined, TEventPublisherServiceName 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>;
+  /** Optional authorization check function */
+  authorize: AuthorizeFn<TServices, TLogger, TSession> | undefined;
+  /** Optional description for documentation */
+  description: string | undefined;
+  /** Optional tags for OpenAPI documentation */
+  tags?: string[];
+  /** Optional execution timeout in milliseconds */
+  timeout: number | undefined;
+  /** Input validation schemas */
+  input: TInput | undefined;
+  /** Output validation schema */
+  output: TOutput | undefined;
+  /** Service dependencies to inject */
+  services: TServices;
+  /** Logger instance */
+  logger: TLogger;
+  /** Optional session extraction function */
+  getSession: SessionFn<TServices, TLogger, TSession> | undefined;
+  /** Optional rate limiting configuration */
+  rateLimit?: RateLimitConfig;
+  /** Success HTTP status code */
+  status: SuccessStatus | undefined;
+  /**
+   * Event publisher service for publishing events from this endpoint
+   */
+  publisherService?: Service<TEventPublisherServiceName, TEventPublisher>;
+  events?: MappedEvent<TEventPublisher, OutSchema>[];
+}
+/**
+ * Defines the possible input schema types for an endpoint.
+ * Each property represents a different part of the HTTP request.
+ */
+type EndpointSchemas = Partial<{
+  /** Schema for URL path parameters (e.g., /users/:id) */
+  params: StandardSchemaV1;
+  /** Schema for query string parameters */
+  query: StandardSchemaV1;
+  /** Schema for request body (POST, PUT, PATCH) */
+  body: StandardSchemaV1;
+}>;
+type AuthorizeContext<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = {
+  services: ServiceRecord<TServices>;
+  logger: TLogger;
+  header: HeaderFn;
+  session: TSession;
+};
+/**
+ * Function type for endpoint authorization checks.
+ *
+ * @template TServices - Available service dependencies
+ * @template TLogger - Logger type
+ * @template TSession - Session data type
+ *
+ * @param ctx - Context containing services, logger, headers, and session
+ * @returns Boolean indicating if the request is authorized
+ *
+ * @example
+ * ```typescript
+ * const authorize: AuthorizeFn = ({ session }) => {
+ *   return session.userId !== undefined;
+ * };
+ * ```
+ */
+type AuthorizeFn<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: AuthorizeContext<TServices, TLogger, TSession>) => Promise<boolean> | boolean;
+type SessionContext<TServices extends Service[] = [], TLogger extends Logger = Logger> = {
+  services: ServiceRecord<TServices>;
+  logger: TLogger;
+  header: HeaderFn;
+};
+/**
+ * Function type for extracting session data from a request.
+ *
+ * @template TServices - Available service dependencies
+ * @template TLogger - Logger type
+ * @template TSession - Session data type to extract
+ *
+ * @param ctx - Context containing services, logger, and headers
+ * @returns The extracted session data
+ *
+ * @example
+ * ```typescript
+ * const getSession: SessionFn<Services, Logger, UserSession> = async ({ header, services }) => {
+ *   const token = header('authorization');
+ *   return await services.auth.verifyToken(token);
+ * };
+ * ```
+ */
+type SessionFn<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: SessionContext<TServices, TLogger>) => Promise<TSession> | TSession;
+/**
+ * Utility type that converts Express-style route parameters to OpenAPI format.
+ * Transforms ':param' syntax to '{param}' syntax.
+ *
+ * @template T - The route string to convert
+ *
+ * @example
+ * ```typescript
+ * type Route1 = ConvertRouteParams<'/users/:id'>; // '/users/{id}'
+ * type Route2 = ConvertRouteParams<'/users/:userId/posts/:postId'>; // '/users/{userId}/posts/{postId}'
+ * ```
+ */
+type ConvertRouteParams<T extends string> = T extends `${infer Start}:${infer Param}/${infer Rest}` ? `${Start}{${Param}}/${ConvertRouteParams<Rest>}` : T extends `${infer Start}:${infer Param}` ? `${Start}{${Param}}` : T;
+/**
+ * Type representing the OpenAPI schema structure for an endpoint.
+ *
+ * @template TRoute - The route path
+ * @template TMethod - The HTTP method
+ *
+ * @example
+ * ```typescript
+ * type Schema = EndpointOpenApiSchema<'/users/:id', 'GET'>;
+ * // Results in: { '/users/{id}': { get: OperationObject, parameters?: ParameterObject[] } }
+ * ```
+ */
+type EndpointOpenApiSchema<TRoute extends string, TMethod extends HttpMethod> = { [key in ConvertRouteParams<TRoute>]: { [key in LowerHttpMethod<TMethod>]: OpenAPIV3_1.OperationObject<{}> } & {
+  parameters?: OpenAPIV3_1.ParameterObject[];
+} };
+type SingleHeaderFn = (key: string) => string | undefined;
+type MultiHeaderFn = () => EndpointHeaders;
+/**
+ * Type representing HTTP headers as a Map.
+ */
+type EndpointHeaders = Map<string, string>;
+/**
+ * Function type for retrieving HTTP header values.
+ *
+ * @param key - The header name (case-insensitive)
+ * @returns The header value or undefined if not found
+ */
+type HeaderFn = SingleHeaderFn;
+/**
+ * The execution context provided to endpoint handlers.
+ * Contains all parsed input data, services, logger, headers, and session.
+ *
+ * @template Input - The input schemas (body, query, params)
+ * @template TServices - Available service dependencies
+ * @template TLogger - Logger type
+ * @template TSession - Session data type
+ */
+type EndpointContext<Input extends EndpointSchemas | undefined = undefined, 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;
+  /** Session data extracted by getSession */
+  session: TSession;
+} & InferComposableStandardSchema<Input>;
+/**
+ * Handler function type for endpoint implementations.
+ *
+ * @template TInput - Input schemas for validation
+ * @template TServices - Available service dependencies
+ * @template TLogger - Logger type
+ * @template OutSchema - Output schema for response validation
+ * @template TSession - Session data type
+ *
+ * @param ctx - The endpoint execution context
+ * @returns The response data (validated if OutSchema is provided)
+ *
+ * @example
+ * ```typescript
+ * const handler: EndpointHandler<Input, [UserService], Logger, UserSchema> =
+ *   async ({ params, services }) => {
+ *     return await services.users.findById(params.id);
+ *   };
+ * ```
+ */
+type EndpointHandler<TInput extends EndpointSchemas | undefined = undefined, TServices extends Service[] = [], TLogger extends Logger = Logger, OutSchema extends StandardSchemaV1 | undefined = undefined, TSession = unknown> = (ctx: EndpointContext<TInput, TServices, TLogger, TSession>) => OutSchema extends StandardSchemaV1 ? InferStandardSchema<OutSchema> | Promise<InferStandardSchema<OutSchema>> : any | Promise<any>;
+/**
+ * HTTP success status codes that can be returned by endpoints.
+ */
+declare enum SuccessStatus {
+  /** Standard response for successful HTTP requests */
+  OK = 200,
+  /** Request has been fulfilled and resulted in a new resource being created */
+  Created = 201,
+  /** Request has been accepted for processing, but processing is not complete */
+  Accepted = 202,
+  /** Server successfully processed the request but is not returning any content */
+  NoContent = 204,
+  /** Server successfully processed the request and is not returning any content, client should reset the document view */
+  ResetContent = 205,
+  /** Server is delivering only part of the resource due to a range header */
+  PartialContent = 206,
+}
+type EndpointOutput<T> = T extends Endpoint<any, any, any, infer OutSchema, any, any, any, any> ? InferStandardSchema<OutSchema> : never;
+type EndpointEvent<T> = T extends Endpoint<any, any, any, any, any, any, any, infer TEventPublisher> ? ExtractPublisherMessage<TEventPublisher> : never;
+//#endregion
+export { AuthorizeContext, AuthorizeFn, ConvertRouteParams, Endpoint, EndpointContext, EndpointEvent, EndpointHandler, EndpointHeaders, EndpointInput, EndpointOpenApiSchema, EndpointOptions, EndpointOutput, EndpointSchemas, HeaderFn, MultiHeaderFn, SessionContext, SessionFn, SingleHeaderFn, SuccessStatus };
+//# sourceMappingURL=Endpoint-C7z9YJHK.d.cts.map