@cosmneo/onion-lasagna 0.1.0

package/dist/routing.type-DB4pt-d9.d.ts

@@ -0,0 +1,184 @@
+import { B as BaseDto } from './base-dto.class-D7W9iqoU.js';
+import { H as HttpRequest, a as HttpResponse, C as Controller } from './http-response-BAhi8lF4.js';
+
+/**
+ * @fileoverview Core routing types for the presentation layer.
+ *
+ * This module provides framework-agnostic routing abstractions that can be
+ * used with any HTTP framework (Hono, Fastify, Elysia, etc.).
+ *
+ * @example Basic route definition
+ * ```typescript
+ * import type { RouteInput } from '@cosmneo/onion-lasagna/backend/core/presentation';
+ *
+ * const getUserRoute: RouteInput<GetUserRequestDto, GetUserResponseDto> = {
+ *   metadata: { path: '/users/{id}', method: 'GET' },
+ *   controller: getUserController,
+ *   requestDtoFactory: (req) => GetUserRequestDto.create(req),
+ * };
+ * ```
+ *
+ * @module routing
+ */
+
+/**
+ * Standard HTTP methods supported by the routing system.
+ *
+ * Includes all methods commonly used in RESTful APIs:
+ * - `GET` - Retrieve a resource
+ * - `POST` - Create a new resource
+ * - `PUT` - Replace a resource
+ * - `PATCH` - Partially update a resource
+ * - `DELETE` - Remove a resource
+ * - `OPTIONS` - CORS preflight and capability discovery
+ * - `HEAD` - Retrieve headers only (no body)
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+/**
+ * HTTP endpoint metadata defining the route's method and path.
+ *
+ * Path parameters use curly brace syntax (`{param}`) which is framework-agnostic.
+ * Each framework adapter converts this to its native format:
+ * - Hono/Express: `/users/:id`
+ * - Fastify: `/users/:id`
+ * - AWS API Gateway: `/users/{id}`
+ *
+ * The `path` should be the full route path (computed from service + resource + endpoint
+ * using `computeRoutePath()` when needed).
+ *
+ * @example Simple route
+ * ```typescript
+ * const metadata: RouteMetadata = {
+ *   path: '/health',
+ *   method: 'GET',
+ * };
+ * ```
+ *
+ * @example Route with path parameters
+ * ```typescript
+ * const metadata: RouteMetadata = {
+ *   path: '/users/{userId}/orders/{orderId}',
+ *   method: 'GET',
+ * };
+ * ```
+ */
+interface RouteMetadata {
+    /**
+     * Full path pattern for the route.
+     *
+     * Uses curly brace syntax for path parameters: `/users/{id}`
+     *
+     * This should be the complete path including service and resource segments.
+     * Use `computeRoutePath()` to compute from service, resource, and endpoint metadata.
+     *
+     * @example '/users'
+     * @example '/users/{id}'
+     * @example '/organizations/{orgId}/members/{memberId}'
+     */
+    path: string;
+    /**
+     * The HTTP method for this route.
+     *
+     * Accepts either uppercase (`'GET'`) or lowercase (`'get'`) format.
+     * Framework adapters normalize to lowercase for registration.
+     */
+    method: HttpMethod | Uppercase<HttpMethod> | Lowercase<HttpMethod>;
+}
+/**
+ * Factory function that creates a validated request DTO from an HTTP request.
+ *
+ * This factory is called by framework adapters to transform the HTTP request
+ * (body, headers, query params, path params) into a validated DTO before passing
+ * to the controller.
+ *
+ * @typeParam TRequestDto - The validated request DTO type (must extend BaseDto)
+ *
+ * @example Creating from HttpRequest
+ * ```typescript
+ * const factory: RequestDtoFactory<CreateUserRequestDto> = (req) =>
+ *   CreateUserRequestDto.create({
+ *     name: req.body.name,
+ *     email: req.body.email,
+ *   });
+ * ```
+ *
+ * @example With path parameters
+ * ```typescript
+ * const factory: RequestDtoFactory<GetUserRequestDto> = (req) =>
+ *   GetUserRequestDto.create({
+ *     userId: req.pathParams?.id,
+ *   });
+ * ```
+ */
+type RequestDtoFactory<TRequestDto extends BaseDto<unknown> = BaseDto<unknown>> = (request: HttpRequest) => TRequestDto;
+/**
+ * Complete route definition combining metadata, controller, and request factory.
+ *
+ * This is the primary type used to define routes in a framework-agnostic way.
+ * Framework adapters (Hono, Fastify, Elysia) accept arrays of `RouteInput` and
+ * register them with the underlying framework.
+ *
+ * The controller receives a validated `TRequestDto` and returns a `TResponseDto`
+ * wrapping an {@link HttpResponse}. Framework adapters extract `.data` from the
+ * response DTO to get the actual HTTP response.
+ *
+ * @typeParam TRequestDto - The validated request DTO type
+ * @typeParam TResponseDto - The response DTO type (wraps HttpResponse)
+ *
+ * @example Single route definition
+ * ```typescript
+ * const createUserRoute: RouteInput<CreateUserRequestDto, CreateUserResponseDto> = {
+ *   metadata: { path: '/users', method: 'POST' },
+ *   controller: createUserController,
+ *   requestDtoFactory: (req) => CreateUserRequestDto.create(req.body),
+ * };
+ * ```
+ *
+ * @example Route array for a resource
+ * ```typescript
+ * const userRoutes: RouteInput[] = [
+ *   {
+ *     metadata: { path: '/users', method: 'GET' },
+ *     controller: listUsersController,
+ *     requestDtoFactory: (req) => ListUsersRequestDto.create(req.queryParams),
+ *   },
+ *   {
+ *     metadata: { path: '/users/{id}', method: 'GET' },
+ *     controller: getUserController,
+ *     requestDtoFactory: (req) => GetUserRequestDto.create(req.pathParams),
+ *   },
+ * ];
+ * ```
+ *
+ * @example Registering with Hono
+ * ```typescript
+ * import { registerHonoRoutes } from '@cosmneo/onion-lasagna/backend/frameworks/hono';
+ *
+ * const app = new Hono();
+ * registerHonoRoutes(app, userRoutes, { prefix: '/api/v1' });
+ * ```
+ */
+interface RouteInput<TRequestDto extends BaseDto<unknown> = BaseDto<unknown>, TResponseDto extends BaseDto<HttpResponse> = BaseDto<HttpResponse>> {
+    /**
+     * Route metadata defining the HTTP method and path.
+     */
+    metadata: RouteMetadata;
+    /**
+     * The controller that handles requests to this route.
+     *
+     * Receives a validated request DTO and returns a response DTO
+     * wrapping an {@link HttpResponse}.
+     */
+    controller: Controller<TRequestDto, TResponseDto>;
+    /**
+     * Factory to create a validated request DTO from the raw framework request.
+     *
+     * The framework adapter calls this factory to transform the raw HTTP request
+     * into a validated DTO before invoking the controller.
+     *
+     * @throws {ObjectValidationError} When the raw request fails DTO validation
+     */
+    requestDtoFactory: RequestDtoFactory<TRequestDto>;
+}
+
+export type { HttpMethod as H, RouteInput as R, RouteMetadata as a, RequestDtoFactory as b };

package/dist/routing.type-DF2BIL7x.d.cts

@@ -0,0 +1,184 @@
+import { B as BaseDto } from './base-dto.class-D7W9iqoU.cjs';
+import { H as HttpRequest, a as HttpResponse, C as Controller } from './http-response-BAhi8lF4.cjs';
+
+/**
+ * @fileoverview Core routing types for the presentation layer.
+ *
+ * This module provides framework-agnostic routing abstractions that can be
+ * used with any HTTP framework (Hono, Fastify, Elysia, etc.).
+ *
+ * @example Basic route definition
+ * ```typescript
+ * import type { RouteInput } from '@cosmneo/onion-lasagna/backend/core/presentation';
+ *
+ * const getUserRoute: RouteInput<GetUserRequestDto, GetUserResponseDto> = {
+ *   metadata: { path: '/users/{id}', method: 'GET' },
+ *   controller: getUserController,
+ *   requestDtoFactory: (req) => GetUserRequestDto.create(req),
+ * };
+ * ```
+ *
+ * @module routing
+ */
+
+/**
+ * Standard HTTP methods supported by the routing system.
+ *
+ * Includes all methods commonly used in RESTful APIs:
+ * - `GET` - Retrieve a resource
+ * - `POST` - Create a new resource
+ * - `PUT` - Replace a resource
+ * - `PATCH` - Partially update a resource
+ * - `DELETE` - Remove a resource
+ * - `OPTIONS` - CORS preflight and capability discovery
+ * - `HEAD` - Retrieve headers only (no body)
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+/**
+ * HTTP endpoint metadata defining the route's method and path.
+ *
+ * Path parameters use curly brace syntax (`{param}`) which is framework-agnostic.
+ * Each framework adapter converts this to its native format:
+ * - Hono/Express: `/users/:id`
+ * - Fastify: `/users/:id`
+ * - AWS API Gateway: `/users/{id}`
+ *
+ * The `path` should be the full route path (computed from service + resource + endpoint
+ * using `computeRoutePath()` when needed).
+ *
+ * @example Simple route
+ * ```typescript
+ * const metadata: RouteMetadata = {
+ *   path: '/health',
+ *   method: 'GET',
+ * };
+ * ```
+ *
+ * @example Route with path parameters
+ * ```typescript
+ * const metadata: RouteMetadata = {
+ *   path: '/users/{userId}/orders/{orderId}',
+ *   method: 'GET',
+ * };
+ * ```
+ */
+interface RouteMetadata {
+    /**
+     * Full path pattern for the route.
+     *
+     * Uses curly brace syntax for path parameters: `/users/{id}`
+     *
+     * This should be the complete path including service and resource segments.
+     * Use `computeRoutePath()` to compute from service, resource, and endpoint metadata.
+     *
+     * @example '/users'
+     * @example '/users/{id}'
+     * @example '/organizations/{orgId}/members/{memberId}'
+     */
+    path: string;
+    /**
+     * The HTTP method for this route.
+     *
+     * Accepts either uppercase (`'GET'`) or lowercase (`'get'`) format.
+     * Framework adapters normalize to lowercase for registration.
+     */
+    method: HttpMethod | Uppercase<HttpMethod> | Lowercase<HttpMethod>;
+}
+/**
+ * Factory function that creates a validated request DTO from an HTTP request.
+ *
+ * This factory is called by framework adapters to transform the HTTP request
+ * (body, headers, query params, path params) into a validated DTO before passing
+ * to the controller.
+ *
+ * @typeParam TRequestDto - The validated request DTO type (must extend BaseDto)
+ *
+ * @example Creating from HttpRequest
+ * ```typescript
+ * const factory: RequestDtoFactory<CreateUserRequestDto> = (req) =>
+ *   CreateUserRequestDto.create({
+ *     name: req.body.name,
+ *     email: req.body.email,
+ *   });
+ * ```
+ *
+ * @example With path parameters
+ * ```typescript
+ * const factory: RequestDtoFactory<GetUserRequestDto> = (req) =>
+ *   GetUserRequestDto.create({
+ *     userId: req.pathParams?.id,
+ *   });
+ * ```
+ */
+type RequestDtoFactory<TRequestDto extends BaseDto<unknown> = BaseDto<unknown>> = (request: HttpRequest) => TRequestDto;
+/**
+ * Complete route definition combining metadata, controller, and request factory.
+ *
+ * This is the primary type used to define routes in a framework-agnostic way.
+ * Framework adapters (Hono, Fastify, Elysia) accept arrays of `RouteInput` and
+ * register them with the underlying framework.
+ *
+ * The controller receives a validated `TRequestDto` and returns a `TResponseDto`
+ * wrapping an {@link HttpResponse}. Framework adapters extract `.data` from the
+ * response DTO to get the actual HTTP response.
+ *
+ * @typeParam TRequestDto - The validated request DTO type
+ * @typeParam TResponseDto - The response DTO type (wraps HttpResponse)
+ *
+ * @example Single route definition
+ * ```typescript
+ * const createUserRoute: RouteInput<CreateUserRequestDto, CreateUserResponseDto> = {
+ *   metadata: { path: '/users', method: 'POST' },
+ *   controller: createUserController,
+ *   requestDtoFactory: (req) => CreateUserRequestDto.create(req.body),
+ * };
+ * ```
+ *
+ * @example Route array for a resource
+ * ```typescript
+ * const userRoutes: RouteInput[] = [
+ *   {
+ *     metadata: { path: '/users', method: 'GET' },
+ *     controller: listUsersController,
+ *     requestDtoFactory: (req) => ListUsersRequestDto.create(req.queryParams),
+ *   },
+ *   {
+ *     metadata: { path: '/users/{id}', method: 'GET' },
+ *     controller: getUserController,
+ *     requestDtoFactory: (req) => GetUserRequestDto.create(req.pathParams),
+ *   },
+ * ];
+ * ```
+ *
+ * @example Registering with Hono
+ * ```typescript
+ * import { registerHonoRoutes } from '@cosmneo/onion-lasagna/backend/frameworks/hono';
+ *
+ * const app = new Hono();
+ * registerHonoRoutes(app, userRoutes, { prefix: '/api/v1' });
+ * ```
+ */
+interface RouteInput<TRequestDto extends BaseDto<unknown> = BaseDto<unknown>, TResponseDto extends BaseDto<HttpResponse> = BaseDto<HttpResponse>> {
+    /**
+     * Route metadata defining the HTTP method and path.
+     */
+    metadata: RouteMetadata;
+    /**
+     * The controller that handles requests to this route.
+     *
+     * Receives a validated request DTO and returns a response DTO
+     * wrapping an {@link HttpResponse}.
+     */
+    controller: Controller<TRequestDto, TResponseDto>;
+    /**
+     * Factory to create a validated request DTO from the raw framework request.
+     *
+     * The framework adapter calls this factory to transform the raw HTTP request
+     * into a validated DTO before invoking the controller.
+     *
+     * @throws {ObjectValidationError} When the raw request fails DTO validation
+     */
+    requestDtoFactory: RequestDtoFactory<TRequestDto>;
+}
+
+export type { HttpMethod as H, RouteInput as R, RouteMetadata as a, RequestDtoFactory as b };

package/dist/validation-error.type-kD4_qNZ9.d.cts

@@ -0,0 +1,199 @@
+/**
+ * Centralized registry of all error codes used across the application.
+ *
+ * Error codes are grouped by architectural layer to maintain clear boundaries
+ * and make it easy to identify where an error originated.
+ *
+ * @example Using error codes in custom errors
+ * ```typescript
+ * import { ErrorCodes } from '@cosmneo/onion-lasagna/backend/core/global';
+ *
+ * throw new NotFoundError({
+ *   message: 'User not found',
+ *   code: ErrorCodes.App.NOT_FOUND,
+ * });
+ * ```
+ *
+ * @example Checking error codes programmatically
+ * ```typescript
+ * if (error.code === ErrorCodes.App.NOT_FOUND) {
+ *   // Handle not found case
+ * }
+ * ```
+ */
+declare const ErrorCodes: {
+    /**
+     * Domain layer error codes.
+     * Used for business rule violations and invariant failures.
+     */
+    readonly Domain: {
+        /** Generic domain error */
+        readonly DOMAIN_ERROR: "DOMAIN_ERROR";
+        /** Business invariant was violated */
+        readonly INVARIANT_VIOLATION: "INVARIANT_VIOLATION";
+        /** Aggregate was partially loaded (missing required relations) */
+        readonly PARTIAL_LOAD: "PARTIAL_LOAD";
+    };
+    /**
+     * Application layer (use case) error codes.
+     * Used for orchestration failures and business operation errors.
+     */
+    readonly App: {
+        /** Generic use case error */
+        readonly USE_CASE_ERROR: "USE_CASE_ERROR";
+        /** Requested resource was not found */
+        readonly NOT_FOUND: "NOT_FOUND";
+        /** Resource state conflict (e.g., duplicate, already exists) */
+        readonly CONFLICT: "CONFLICT";
+        /** Request is valid but cannot be processed due to business rules */
+        readonly UNPROCESSABLE: "UNPROCESSABLE";
+    };
+    /**
+     * Infrastructure layer error codes.
+     * Used for data access, external services, and I/O failures.
+     */
+    readonly Infra: {
+        /** Generic infrastructure error */
+        readonly INFRA_ERROR: "INFRA_ERROR";
+        /** Database operation failed */
+        readonly DB_ERROR: "DB_ERROR";
+        /** Network connectivity or communication error */
+        readonly NETWORK_ERROR: "NETWORK_ERROR";
+        /** Operation timed out */
+        readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+        /** External/third-party service error */
+        readonly EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR";
+    };
+    /**
+     * Presentation layer error codes.
+     * Used for controller, request handling, and authorization errors.
+     */
+    readonly Presentation: {
+        /** Generic controller error */
+        readonly CONTROLLER_ERROR: "CONTROLLER_ERROR";
+        /** Request denied due to authorization failure */
+        readonly ACCESS_DENIED: "ACCESS_DENIED";
+        /** Request validation failed (malformed input) */
+        readonly INVALID_REQUEST: "INVALID_REQUEST";
+    };
+    /**
+     * Global/cross-cutting error codes.
+     * Used for validation and other cross-layer concerns.
+     */
+    readonly Global: {
+        /** Object/schema validation failed */
+        readonly OBJECT_VALIDATION_ERROR: "OBJECT_VALIDATION_ERROR";
+    };
+};
+/**
+ * Type representing all possible domain error codes.
+ */
+type DomainErrorCode = (typeof ErrorCodes.Domain)[keyof typeof ErrorCodes.Domain];
+/**
+ * Type representing all possible application error codes.
+ */
+type AppErrorCode = (typeof ErrorCodes.App)[keyof typeof ErrorCodes.App];
+/**
+ * Type representing all possible infrastructure error codes.
+ */
+type InfraErrorCode = (typeof ErrorCodes.Infra)[keyof typeof ErrorCodes.Infra];
+/**
+ * Type representing all possible presentation error codes.
+ */
+type PresentationErrorCode = (typeof ErrorCodes.Presentation)[keyof typeof ErrorCodes.Presentation];
+/**
+ * Type representing all possible global error codes.
+ */
+type GlobalErrorCode = (typeof ErrorCodes.Global)[keyof typeof ErrorCodes.Global];
+/**
+ * Union type of all error codes across all layers.
+ *
+ * Use this when you need to accept any valid error code.
+ *
+ * @example
+ * ```typescript
+ * function logError(code: ErrorCode, message: string) {
+ *   console.error(`[${code}] ${message}`);
+ * }
+ * ```
+ */
+type ErrorCode = DomainErrorCode | AppErrorCode | InfraErrorCode | PresentationErrorCode | GlobalErrorCode;
+
+/**
+ * Base error class for all application errors with a machine-readable code.
+ *
+ * Abstract class that extends the native `Error` with:
+ * - A `code` property for programmatic error handling
+ * - Optional `cause` for error chaining (ES2022 compatible)
+ * - A `fromError` static factory pattern for error transformation
+ *
+ * **Why abstract:** Prevents non-declarative error usage. All errors must
+ * be explicitly defined as subclasses to ensure consistent error taxonomy.
+ *
+ * @example Subclass implementation
+ * ```typescript
+ * class DbError extends InfraError {
+ *   static override fromError(cause: unknown): DbError {
+ *     return new DbError({
+ *       message: cause instanceof Error ? cause.message : 'Database error',
+ *       cause,
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Usage with wrapErrorAsync
+ * ```typescript
+ * await wrapErrorAsync(
+ *   () => this.db.query(...),
+ *   DbError.fromError,
+ * );
+ * ```
+ */
+declare abstract class CodedError extends Error {
+    /** Machine-readable error code for programmatic handling. */
+    readonly code: ErrorCode | string;
+    /**
+     * Creates a new CodedError instance.
+     *
+     * @param options - Error configuration
+     * @param options.message - Human-readable error message
+     * @param options.code - Machine-readable error code from ErrorCodes registry or custom string
+     * @param options.cause - Optional underlying error that caused this error
+     */
+    constructor({ message, code, cause, }: {
+        message: string;
+        code: ErrorCode | string;
+        cause?: unknown;
+    });
+    /**
+     * Factory method to create a typed error from a caught error.
+     *
+     * Subclasses should override this to provide proper error transformation.
+     * Designed for use with {@link wrapErrorAsync} and {@link wrapError}.
+     *
+     * @param _cause - The original caught error
+     * @returns A new CodedError instance
+     * @throws {Error} If not overridden by subclass
+     *
+     * @example
+     * ```typescript
+     * class NotFoundError extends UseCaseError {
+     *   static override fromError(cause: unknown): NotFoundError {
+     *     return new NotFoundError({
+     *       message: 'Resource not found',
+     *       cause,
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    static fromError(_cause: unknown): CodedError;
+}
+
+interface ValidationError {
+    field: string;
+    message: string;
+}
+
+export { type AppErrorCode as A, CodedError as C, type DomainErrorCode as D, ErrorCodes as E, type GlobalErrorCode as G, type InfraErrorCode as I, type PresentationErrorCode as P, type ValidationError as V, type ErrorCode as a };