@cosmneo/onion-lasagna 0.1.0

package/dist/backend/core/presentation.cjs

@@ -0,0 +1,573 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/backend/core/onion-layers/presentation/index.ts
+var presentation_exports = {};
+__export(presentation_exports, {
+  AccessDeniedError: () => AccessDeniedError,
+  BaseController: () => BaseController,
+  ControllerError: () => ControllerError,
+  GuardedController: () => GuardedController,
+  InvalidRequestError: () => InvalidRequestError,
+  assertHttpResponse: () => assertHttpResponse,
+  computeRoutePath: () => computeRoutePath,
+  defineSystemMetadata: () => defineSystemMetadata,
+  isHttpResponse: () => isHttpResponse
+});
+module.exports = __toCommonJS(presentation_exports);
+
+// src/backend/core/global/exceptions/coded-error.error.ts
+var CodedError = class extends Error {
+  /** Machine-readable error code for programmatic handling. */
+  code;
+  /**
+   * 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
+  }) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        writable: false,
+        enumerable: false,
+        configurable: true
+      });
+    }
+  }
+  /**
+   * 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) {
+    throw new Error(`${this.name}.fromError() must be implemented by subclass`);
+  }
+};
+
+// src/backend/core/global/exceptions/error-codes.const.ts
+var ErrorCodes = {
+  /**
+   * Domain layer error codes.
+   * Used for business rule violations and invariant failures.
+   */
+  Domain: {
+    /** Generic domain error */
+    DOMAIN_ERROR: "DOMAIN_ERROR",
+    /** Business invariant was violated */
+    INVARIANT_VIOLATION: "INVARIANT_VIOLATION",
+    /** Aggregate was partially loaded (missing required relations) */
+    PARTIAL_LOAD: "PARTIAL_LOAD"
+  },
+  /**
+   * Application layer (use case) error codes.
+   * Used for orchestration failures and business operation errors.
+   */
+  App: {
+    /** Generic use case error */
+    USE_CASE_ERROR: "USE_CASE_ERROR",
+    /** Requested resource was not found */
+    NOT_FOUND: "NOT_FOUND",
+    /** Resource state conflict (e.g., duplicate, already exists) */
+    CONFLICT: "CONFLICT",
+    /** Request is valid but cannot be processed due to business rules */
+    UNPROCESSABLE: "UNPROCESSABLE"
+  },
+  /**
+   * Infrastructure layer error codes.
+   * Used for data access, external services, and I/O failures.
+   */
+  Infra: {
+    /** Generic infrastructure error */
+    INFRA_ERROR: "INFRA_ERROR",
+    /** Database operation failed */
+    DB_ERROR: "DB_ERROR",
+    /** Network connectivity or communication error */
+    NETWORK_ERROR: "NETWORK_ERROR",
+    /** Operation timed out */
+    TIMEOUT_ERROR: "TIMEOUT_ERROR",
+    /** External/third-party service error */
+    EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR"
+  },
+  /**
+   * Presentation layer error codes.
+   * Used for controller, request handling, and authorization errors.
+   */
+  Presentation: {
+    /** Generic controller error */
+    CONTROLLER_ERROR: "CONTROLLER_ERROR",
+    /** Request denied due to authorization failure */
+    ACCESS_DENIED: "ACCESS_DENIED",
+    /** Request validation failed (malformed input) */
+    INVALID_REQUEST: "INVALID_REQUEST"
+  },
+  /**
+   * Global/cross-cutting error codes.
+   * Used for validation and other cross-layer concerns.
+   */
+  Global: {
+    /** Object/schema validation failed */
+    OBJECT_VALIDATION_ERROR: "OBJECT_VALIDATION_ERROR"
+  }
+};
+
+// src/backend/core/global/exceptions/object-validation.error.ts
+var ObjectValidationError = class _ObjectValidationError extends CodedError {
+  /**
+   * Array of field-level validation errors.
+   *
+   * Each entry contains:
+   * - `field`: Dot-notation path to the invalid field (e.g., 'user.email')
+   * - `message`: Human-readable validation failure message
+   */
+  validationErrors;
+  /**
+   * Creates a new ObjectValidationError instance.
+   *
+   * @param options - Error configuration
+   * @param options.message - Human-readable summary message
+   * @param options.code - Machine-readable error code (default: 'OBJECT_VALIDATION_ERROR')
+   * @param options.cause - Optional underlying error from validation library
+   * @param options.validationErrors - Array of field-level validation errors
+   */
+  constructor({
+    message,
+    code = ErrorCodes.Global.OBJECT_VALIDATION_ERROR,
+    cause,
+    validationErrors
+  }) {
+    super({ message, code, cause });
+    this.validationErrors = validationErrors;
+  }
+  /**
+   * Creates an ObjectValidationError from a caught error.
+   *
+   * @param cause - The original caught error
+   * @returns A new ObjectValidationError instance with the cause attached
+   */
+  static fromError(cause) {
+    return new _ObjectValidationError({
+      message: cause instanceof Error ? cause.message : "Validation failed",
+      cause,
+      validationErrors: []
+    });
+  }
+};
+
+// src/backend/core/global/utils/wrap-error.util.ts
+function wrapErrorUnless(fn, errorFactory, passthroughTypes) {
+  try {
+    return fn();
+  } catch (error) {
+    if (passthroughTypes.some((Type) => error instanceof Type)) {
+      throw error;
+    }
+    throw errorFactory(error);
+  }
+}
+async function wrapErrorUnlessAsync(fn, errorFactory, passthroughTypes) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (passthroughTypes.some((Type) => error instanceof Type)) {
+      throw error;
+    }
+    throw errorFactory(error);
+  }
+}
+
+// src/backend/core/onion-layers/presentation/exceptions/controller.error.ts
+var ControllerError = class _ControllerError extends CodedError {
+  /**
+   * Creates a new ControllerError instance.
+   *
+   * @param options - Error configuration
+   * @param options.message - Human-readable error description
+   * @param options.code - Machine-readable error code (default: 'CONTROLLER_ERROR')
+   * @param options.cause - Optional underlying error
+   */
+  constructor({
+    message,
+    code = ErrorCodes.Presentation.CONTROLLER_ERROR,
+    cause
+  }) {
+    super({ message, code, cause });
+  }
+  /**
+   * Creates a ControllerError from a caught error.
+   *
+   * @param cause - The original caught error
+   * @returns A new ControllerError instance with the cause attached
+   */
+  static fromError(cause) {
+    return new _ControllerError({
+      message: cause instanceof Error ? cause.message : "Controller error",
+      cause
+    });
+  }
+};
+
+// src/backend/core/onion-layers/presentation/exceptions/invalid-request.error.ts
+var InvalidRequestError = class _InvalidRequestError extends CodedError {
+  /**
+   * Array of field-level validation errors.
+   *
+   * Each entry contains:
+   * - `field`: Dot-notation path to the invalid field
+   * - `message`: Human-readable validation failure message
+   */
+  validationErrors;
+  /**
+   * Creates a new InvalidRequestError instance.
+   *
+   * @param options - Error configuration
+   * @param options.message - Summary of the validation failure
+   * @param options.code - Machine-readable error code (default: 'INVALID_REQUEST')
+   * @param options.cause - Optional underlying error
+   * @param options.validationErrors - Array of field-level validation errors
+   */
+  constructor({
+    message,
+    code = ErrorCodes.Presentation.INVALID_REQUEST,
+    cause,
+    validationErrors
+  }) {
+    super({ message, code, cause });
+    this.validationErrors = validationErrors;
+  }
+  /**
+   * Creates an InvalidRequestError from a caught error.
+   *
+   * @param cause - The original caught error
+   * @returns A new InvalidRequestError instance with the cause attached
+   */
+  static fromError(cause) {
+    return new _InvalidRequestError({
+      message: cause instanceof Error ? cause.message : "Invalid request",
+      cause,
+      validationErrors: []
+    });
+  }
+};
+
+// src/backend/core/onion-layers/presentation/classes/base-controller.class.ts
+var BaseController = class _BaseController {
+  /**
+   * Creates a new BaseController instance.
+   *
+   * @param requestMapper - Function to map request DTO to use case input DTO
+   * @param useCase - The use case port to execute
+   * @param responseMapper - Function to map use case output DTO to response DTO
+   */
+  constructor(requestMapper, useCase, responseMapper) {
+    this.requestMapper = requestMapper;
+    this.useCase = useCase;
+    this.responseMapper = responseMapper;
+  }
+  /**
+   * Factory method to create a controller from a configuration object.
+   *
+   * @param config - Controller configuration
+   * @returns A new BaseController instance
+   */
+  static create(config) {
+    return new _BaseController(config.requestMapper, config.useCase, config.responseMapper);
+  }
+  /**
+   * Executes the controller pipeline with error wrapping.
+   *
+   * This is the public entry point that ensures consistent error handling.
+   * All errors are wrapped in {@link ControllerError} unless they extend {@link CodedError}.
+   *
+   * **Do not override this method.** Override {@link pipeline} instead for custom pipeline logic.
+   *
+   * @param input - The validated request DTO
+   * @returns Promise resolving to the validated response DTO
+   * @throws {InvalidRequestError} When request mapping/validation fails
+   * @throws {ControllerError} When an unexpected error occurs
+   * @throws {CodedError} When use case throws a known error type
+   */
+  async execute(input) {
+    return wrapErrorUnlessAsync(
+      () => this.pipeline(input),
+      (cause) => new ControllerError({
+        message: cause instanceof Error ? cause.message : "Controller execution failed",
+        cause
+      }),
+      [CodedError]
+    );
+  }
+  /**
+   * Runs the controller pipeline.
+   *
+   * Orchestrates: `mapRequest → executeUseCase → mapResponse`
+   *
+   * Override this method to customize the entire pipeline flow, or override
+   * individual protected methods ({@link mapRequest}, {@link executeUseCase},
+   * {@link mapResponse}) for more granular control.
+   *
+   * @param input - The validated request DTO
+   * @returns Promise resolving to the validated response DTO
+   */
+  async pipeline(input) {
+    const mappedInput = this.mapRequest(input);
+    const result = await this.executeUseCase(mappedInput);
+    return this.mapResponse(result);
+  }
+  /**
+   * Maps the request DTO to a use case input DTO.
+   *
+   * Override to add custom pre-processing, logging, or transformation logic.
+   * The default implementation uses the configured `requestMapper` and converts
+   * {@link ObjectValidationError} to {@link InvalidRequestError}.
+   *
+   * @param input - The validated request DTO
+   * @returns The use case input DTO
+   * @throws {InvalidRequestError} When validation fails
+   * @throws {ControllerError} When mapping fails unexpectedly
+   */
+  mapRequest(input) {
+    return wrapErrorUnless(
+      () => this.requestMapper(input),
+      (cause) => {
+        if (cause instanceof ObjectValidationError) {
+          return new InvalidRequestError({
+            message: cause.message,
+            cause,
+            validationErrors: cause.validationErrors
+          });
+        }
+        return new ControllerError({
+          message: cause instanceof Error ? cause.message : "Request mapping failed",
+          cause
+        });
+      },
+      [CodedError]
+    );
+  }
+  /**
+   * Executes the use case with the mapped input.
+   *
+   * Override to add custom logic around use case execution, such as:
+   * - Logging/tracing
+   * - Caching
+   * - Retry logic
+   * - Multi-use-case orchestration
+   *
+   * @param input - The use case input DTO
+   * @returns Promise resolving to the use case output DTO
+   */
+  async executeUseCase(input) {
+    return this.useCase.execute(input);
+  }
+  /**
+   * Maps the use case output DTO to a response DTO.
+   *
+   * Override to add custom post-processing, logging, or transformation logic.
+   * The default implementation uses the configured `responseMapper`.
+   *
+   * @param output - The use case output DTO
+   * @returns The response DTO
+   * @throws {ControllerError} When mapping or validation fails
+   */
+  mapResponse(output) {
+    return wrapErrorUnless(
+      () => this.responseMapper(output),
+      (cause) => new ControllerError({
+        message: cause instanceof ObjectValidationError ? "Response validation failed" : cause instanceof Error ? cause.message : "Response mapping failed",
+        cause
+      }),
+      [CodedError]
+    );
+  }
+};
+
+// src/backend/core/onion-layers/presentation/exceptions/access-denied.error.ts
+var AccessDeniedError = class _AccessDeniedError extends CodedError {
+  /**
+   * Creates a new AccessDeniedError instance.
+   *
+   * @param options - Error configuration
+   * @param options.message - Description of why access was denied
+   * @param options.code - Machine-readable error code (default: 'ACCESS_DENIED')
+   * @param options.cause - Optional underlying error
+   */
+  constructor({
+    message,
+    code = ErrorCodes.Presentation.ACCESS_DENIED,
+    cause
+  }) {
+    super({ message, code, cause });
+  }
+  /**
+   * Creates an AccessDeniedError from a caught error.
+   *
+   * @param cause - The original caught error
+   * @returns A new AccessDeniedError instance with the cause attached
+   */
+  static fromError(cause) {
+    return new _AccessDeniedError({
+      message: cause instanceof Error ? cause.message : "Access denied",
+      cause
+    });
+  }
+};
+
+// src/backend/core/onion-layers/presentation/classes/guarded-controller.class.ts
+function createAllowAllGuard() {
+  return async () => ({
+    isAllowed: true
+  });
+}
+var GuardedController = class _GuardedController extends BaseController {
+  /** The access guard function for this controller. */
+  accessGuard;
+  /**
+   * Creates a new GuardedController instance.
+   *
+   * @param requestMapper - Function to map request DTO to use case input DTO
+   * @param useCase - The use case port to execute
+   * @param responseMapper - Function to map use case output DTO to response DTO
+   * @param accessGuard - Optional access guard; defaults to allowing all
+   */
+  constructor(requestMapper, useCase, responseMapper, accessGuard) {
+    super(requestMapper, useCase, responseMapper);
+    this.accessGuard = accessGuard ?? createAllowAllGuard();
+  }
+  /**
+   * Factory method to create a guarded controller from a configuration object.
+   *
+   * @param config - Controller configuration including optional access guard
+   * @returns A new GuardedController instance
+   */
+  static create(config) {
+    return new _GuardedController(
+      config.requestMapper,
+      config.useCase,
+      config.responseMapper,
+      config.accessGuard
+    );
+  }
+  /**
+   * Runs the controller pipeline with access control.
+   *
+   * Checks the access guard before executing the pipeline.
+   * If denied, throws {@link AccessDeniedError}.
+   *
+   * @param input - The validated request DTO
+   * @returns Promise resolving to the validated response DTO
+   * @throws {AccessDeniedError} When access guard denies the request
+   */
+  async pipeline(input) {
+    await this.checkAccess(input);
+    return super.pipeline(input);
+  }
+  /**
+   * Checks access using the configured guard.
+   *
+   * Override to customize access control logic.
+   *
+   * @param input - The validated request DTO
+   * @throws {AccessDeniedError} When access is denied
+   */
+  async checkAccess(input) {
+    const result = await this.accessGuard(input);
+    if (!result.isAllowed) {
+      throw new AccessDeniedError({
+        message: result.reason ?? "Access denied"
+      });
+    }
+  }
+};
+
+// src/backend/core/onion-layers/presentation/interfaces/types/metadata/system-metadata.type.ts
+function defineSystemMetadata(metadata) {
+  return metadata;
+}
+
+// src/backend/core/onion-layers/presentation/routing/compute-route-path.util.ts
+function trimSlashes(segment) {
+  return segment.replace(/^\/+|\/+$/g, "");
+}
+function computeRoutePath(service, resource, endpoint) {
+  const segments = [service.basePath, resource.path, endpoint.path].map(trimSlashes).filter((s) => s.length > 0);
+  if (segments.length === 0) {
+    return "/";
+  }
+  return "/" + segments.join("/");
+}
+
+// src/backend/core/onion-layers/presentation/utils/http-response.util.ts
+function isHttpResponse(value) {
+  return typeof value === "object" && value !== null && "statusCode" in value && typeof value.statusCode === "number";
+}
+function assertHttpResponse(value, context = "value") {
+  if (!isHttpResponse(value)) {
+    const actualType = value === null ? "null" : value === void 0 ? "undefined" : typeof value;
+    const hasStatusCode = typeof value === "object" && value !== null && "statusCode" in value;
+    let message = `Expected ${context} to be an HttpResponse with a numeric statusCode, `;
+    if (hasStatusCode) {
+      const statusCodeType = typeof value["statusCode"];
+      message += `but statusCode was ${statusCodeType}`;
+    } else {
+      message += `but got ${actualType}`;
+    }
+    throw new Error(message);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AccessDeniedError,
+  BaseController,
+  ControllerError,
+  GuardedController,
+  InvalidRequestError,
+  assertHttpResponse,
+  computeRoutePath,
+  defineSystemMetadata,
+  isHttpResponse
+});
+//# sourceMappingURL=presentation.cjs.map