@cosmneo/onion-lasagna 0.1.0

package/dist/http-response-BAhi8lF4.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Base controller interface for the presentation layer.
+ *
+ * All controllers must implement this interface. The {@link BaseController} class
+ * provides a standard request/response pipeline implementation.
+ *
+ * @typeParam TInput - The input type the controller accepts
+ * @typeParam TOutput - The output type the controller returns
+ *
+ * @example Using BaseController (recommended)
+ * ```typescript
+ * const controller = BaseController.create({
+ *   requestMapper: (req) => CreateUserInputDto.create(req.body),
+ *   useCase: createUserUseCase,
+ *   responseMapper: (output) => ({ statusCode: 201, body: output.value }),
+ * });
+ * ```
+ *
+ * @example Custom implementation
+ * ```typescript
+ * class MyController implements Controller<MyInput, MyOutput> {
+ *   async execute(input: MyInput): Promise<MyOutput> {
+ *     // custom logic
+ *   }
+ * }
+ * ```
+ */
+interface Controller<TInput = unknown, TOutput = unknown> {
+    /**
+     * Executes the controller with the given input.
+     *
+     * @param input - The input to process
+     * @returns Promise resolving to the output
+     */
+    execute(input: TInput): Promise<TOutput>;
+}
+
+/**
+ * Basic HTTP request structure for any HTTP-based framework.
+ *
+ * This is the foundation type representing the data extracted from an HTTP request.
+ * Frameworks (AWS API Gateway, Cloudflare Workers, Express, etc.) map their native
+ * request types to this common interface.
+ *
+ * @example Complete request
+ * ```typescript
+ * const request: HttpRequest = {
+ *   body: { name: 'John', email: 'john@example.com' },
+ *   headers: { 'content-type': 'application/json', 'authorization': 'Bearer ...' },
+ *   pathParams: { id: '123' },
+ *   queryParams: { include: 'profile' },
+ * };
+ * ```
+ */
+interface HttpRequest {
+    /**
+     * Parsed request body.
+     * For JSON requests, this is the deserialized object.
+     * For form data, this contains the parsed form fields.
+     */
+    body?: unknown;
+    /**
+     * HTTP request headers (normalized to lowercase keys).
+     * Common headers include authorization, content-type, accept, etc.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Query string parameters from the URL.
+     * For `/users?page=1&limit=10`, this would be `{ page: '1', limit: '10' }`.
+     * When a key appears multiple times (e.g., `?tag=a&tag=b`), the value is an array.
+     */
+    queryParams?: Record<string, string | string[]>;
+    /**
+     * Path parameters extracted from the URL pattern.
+     * For route `/users/:id` and URL `/users/123`, this would be `{ id: '123' }`.
+     */
+    pathParams?: Record<string, string>;
+}
+
+/**
+ * Basic HTTP response structure for any HTTP-based framework.
+ *
+ * This is the foundation type representing the data to send as an HTTP response.
+ * Frameworks (AWS API Gateway, Cloudflare Workers, Express, etc.) map this common
+ * interface to their native response types.
+ *
+ * @example Success response
+ * ```typescript
+ * const response: HttpResponse = {
+ *   statusCode: 200,
+ *   body: { id: '123', name: 'John' },
+ * };
+ * ```
+ *
+ * @example Response with headers
+ * ```typescript
+ * const response: HttpResponse = {
+ *   statusCode: 201,
+ *   headers: {
+ *     'Location': '/users/123',
+ *     'X-Request-Id': 'req-abc',
+ *   },
+ *   body: { id: '123' },
+ * };
+ * ```
+ */
+interface HttpResponse {
+    /**
+     * HTTP status code (e.g., 200, 201, 400, 404, 500).
+     */
+    statusCode: number;
+    /**
+     * Optional response headers.
+     * Common headers include Content-Type, Location, Cache-Control, etc.
+     */
+    headers?: Record<string, unknown>;
+    /**
+     * Optional response body.
+     * Will be serialized to JSON by framework adapters if it's an object.
+     */
+    body?: unknown;
+}
+
+export type { Controller as C, HttpRequest as H, HttpResponse as a };