@cosmneo/onion-lasagna 0.1.0

package/dist/chunk-74IKUOSE.js

@@ -0,0 +1,116 @@
+import {
+  CodedError,
+  ErrorCodes
+} from "./chunk-MQD5GXMT.js";
+
+// 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/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
+    });
+  }
+};
+
+export {
+  ControllerError,
+  InvalidRequestError,
+  AccessDeniedError
+};
+//# sourceMappingURL=chunk-74IKUOSE.js.map

package/dist/chunk-74IKUOSE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/backend/core/onion-layers/presentation/exceptions/controller.error.ts","../src/backend/core/onion-layers/presentation/exceptions/invalid-request.error.ts","../src/backend/core/onion-layers/presentation/exceptions/access-denied.error.ts"],"sourcesContent":["import { CodedError } from '../../../global/exceptions/coded-error.error';\nimport {\n  ErrorCodes,\n  type PresentationErrorCode,\n} from '../../../global/exceptions/error-codes.const';\n\n/**\n * Base error class for presentation layer (controller) failures.\n *\n * Controller errors represent failures in request handling,\n * such as access control violations or malformed requests.\n * They are the outermost error layer and typically map to HTTP responses.\n *\n * **When to throw:**\n * - Access control failures (unauthorized/forbidden)\n * - Request validation failures\n * - Unexpected controller execution errors\n *\n * **Child classes:**\n * - {@link AccessDeniedError} - Authorization failures (HTTP 403)\n * - {@link InvalidRequestError} - Request validation failures (HTTP 400)\n *\n * @example\n * ```typescript\n * // Thrown automatically by BaseController for unexpected errors\n * throw new ControllerError({\n *   message: 'Controller execution failed',\n *   cause: originalError,\n * });\n * ```\n */\nexport class ControllerError extends CodedError {\n  /**\n   * Creates a new ControllerError instance.\n   *\n   * @param options - Error configuration\n   * @param options.message - Human-readable error description\n   * @param options.code - Machine-readable error code (default: 'CONTROLLER_ERROR')\n   * @param options.cause - Optional underlying error\n   */\n  constructor({\n    message,\n    code = ErrorCodes.Presentation.CONTROLLER_ERROR,\n    cause,\n  }: {\n    message: string;\n    code?: PresentationErrorCode | string;\n    cause?: unknown;\n  }) {\n    super({ message, code, cause });\n  }\n\n  /**\n   * Creates a ControllerError from a caught error.\n   *\n   * @param cause - The original caught error\n   * @returns A new ControllerError instance with the cause attached\n   */\n  static override fromError(cause: unknown): ControllerError {\n    return new ControllerError({\n      message: cause instanceof Error ? cause.message : 'Controller error',\n      cause,\n    });\n  }\n}\n","import { CodedError } from '../../../global/exceptions/coded-error.error';\nimport {\n  ErrorCodes,\n  type PresentationErrorCode,\n} from '../../../global/exceptions/error-codes.const';\nimport type { ValidationError } from '../../../global/interfaces/types/validation-error.type';\n\n/**\n * Error thrown when request validation fails at the controller level.\n *\n * Contains structured validation errors with field paths and messages,\n * converted from {@link ObjectValidationError} by {@link BaseController}.\n * Provides detailed feedback about which fields failed validation.\n *\n * **When thrown:**\n * - Request DTO validation fails\n * - Malformed request data\n * - Missing required fields\n *\n * @example\n * ```typescript\n * // Automatically thrown by BaseController when DTO validation fails\n * // The validationErrors array contains field-level details:\n * // [\n * //   { field: 'email', message: 'Invalid email format' },\n * //   { field: 'age', message: 'Must be a positive number' }\n * // ]\n * ```\n *\n * @example Manual usage\n * ```typescript\n * throw new InvalidRequestError({\n *   message: 'Request validation failed',\n *   validationErrors: [\n *     { field: 'username', message: 'Username is required' },\n *   ],\n * });\n * ```\n *\n * @extends CodedError\n */\nexport class InvalidRequestError extends CodedError {\n  /**\n   * Array of field-level validation errors.\n   *\n   * Each entry contains:\n   * - `field`: Dot-notation path to the invalid field\n   * - `message`: Human-readable validation failure message\n   */\n  readonly validationErrors: ValidationError[];\n\n  /**\n   * Creates a new InvalidRequestError instance.\n   *\n   * @param options - Error configuration\n   * @param options.message - Summary of the validation failure\n   * @param options.code - Machine-readable error code (default: 'INVALID_REQUEST')\n   * @param options.cause - Optional underlying error\n   * @param options.validationErrors - Array of field-level validation errors\n   */\n  constructor({\n    message,\n    code = ErrorCodes.Presentation.INVALID_REQUEST,\n    cause,\n    validationErrors,\n  }: {\n    message: string;\n    code?: PresentationErrorCode | string;\n    cause?: unknown;\n    validationErrors: ValidationError[];\n  }) {\n    super({ message, code, cause });\n    this.validationErrors = validationErrors;\n  }\n\n  /**\n   * Creates an InvalidRequestError from a caught error.\n   *\n   * @param cause - The original caught error\n   * @returns A new InvalidRequestError instance with the cause attached\n   */\n  static override fromError(cause: unknown): InvalidRequestError {\n    return new InvalidRequestError({\n      message: cause instanceof Error ? cause.message : 'Invalid request',\n      cause,\n      validationErrors: [],\n    });\n  }\n}\n","import { CodedError } from '../../../global/exceptions/coded-error.error';\nimport {\n  ErrorCodes,\n  type PresentationErrorCode,\n} from '../../../global/exceptions/error-codes.const';\n\n/**\n * Error thrown when access to a resource is denied.\n *\n * Indicates that the requester does not have permission to perform\n * the requested operation. Thrown by {@link GuardedController} when\n * an access guard returns `isAllowed: false`.\n *\n * **When thrown:**\n * - Access guard denies the request\n * - User lacks required permissions\n * - Resource ownership check fails\n *\n * @example GuardedController usage\n * ```typescript\n * const controller = GuardedController.create({\n *   accessGuard: (req) => ({\n *     isAllowed: req.user?.role === 'admin',\n *     reason: 'Admin access required',\n *   }),\n *   // ... other config\n * });\n * ```\n *\n * @example Manual usage\n * ```typescript\n * if (!user.canAccess(resource)) {\n *   throw new AccessDeniedError({\n *     message: 'You do not have access to this resource',\n *     code: 'RESOURCE_ACCESS_DENIED',\n *   });\n * }\n * ```\n *\n * @extends CodedError\n */\nexport class AccessDeniedError extends CodedError {\n  /**\n   * Creates a new AccessDeniedError instance.\n   *\n   * @param options - Error configuration\n   * @param options.message - Description of why access was denied\n   * @param options.code - Machine-readable error code (default: 'ACCESS_DENIED')\n   * @param options.cause - Optional underlying error\n   */\n  constructor({\n    message,\n    code = ErrorCodes.Presentation.ACCESS_DENIED,\n    cause,\n  }: {\n    message: string;\n    code?: PresentationErrorCode | string;\n    cause?: unknown;\n  }) {\n    super({ message, code, cause });\n  }\n\n  /**\n   * Creates an AccessDeniedError from a caught error.\n   *\n   * @param cause - The original caught error\n   * @returns A new AccessDeniedError instance with the cause attached\n   */\n  static override fromError(cause: unknown): AccessDeniedError {\n    return new AccessDeniedError({\n      message: cause instanceof Error ? cause.message : 'Access denied',\n      cause,\n    });\n  }\n}\n"],"mappings":";;;;;;AA+BO,IAAM,kBAAN,MAAM,yBAAwB,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAS9C,YAAY;AAAA,IACV;AAAA,IACA,OAAO,WAAW,aAAa;AAAA,IAC/B;AAAA,EACF,GAIG;AACD,UAAM,EAAE,SAAS,MAAM,MAAM,CAAC;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAgB,UAAU,OAAiC;AACzD,WAAO,IAAI,iBAAgB;AAAA,MACzB,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MAClD;AAAA,IACF,CAAC;AAAA,EACH;AACF;;;ACvBO,IAAM,sBAAN,MAAM,6BAA4B,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWT,YAAY;AAAA,IACV;AAAA,IACA,OAAO,WAAW,aAAa;AAAA,IAC/B;AAAA,IACA;AAAA,EACF,GAKG;AACD,UAAM,EAAE,SAAS,MAAM,MAAM,CAAC;AAC9B,SAAK,mBAAmB;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAgB,UAAU,OAAqC;AAC7D,WAAO,IAAI,qBAAoB;AAAA,MAC7B,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MAClD;AAAA,MACA,kBAAkB,CAAC;AAAA,IACrB,CAAC;AAAA,EACH;AACF;;;AC/CO,IAAM,oBAAN,MAAM,2BAA0B,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAShD,YAAY;AAAA,IACV;AAAA,IACA,OAAO,WAAW,aAAa;AAAA,IAC/B;AAAA,EACF,GAIG;AACD,UAAM,EAAE,SAAS,MAAM,MAAM,CAAC;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAgB,UAAU,OAAmC;AAC3D,WAAO,IAAI,mBAAkB;AAAA,MAC3B,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MAClD;AAAA,IACF,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/chunk-BKZOLGQW.js

@@ -0,0 +1,29 @@
+// src/backend/core/global/classes/base-dto.class.ts
+var SKIP_DTO_VALIDATION = "skip dto validation";
+var BaseDto = class {
+  _data;
+  /**
+   * Creates a new DTO instance.
+   *
+   * @param data - The raw data to validate and wrap
+   * @param validator - A bound validator or SKIP_DTO_VALIDATION to bypass
+   * @throws {ObjectValidationError} When validation fails
+   */
+  constructor(data, validator) {
+    this._data = validator === SKIP_DTO_VALIDATION ? data : validator.validate(data);
+  }
+  /**
+   * The validated data payload.
+   *
+   * @returns The validated data of type T
+   */
+  get data() {
+    return this._data;
+  }
+};
+
+export {
+  SKIP_DTO_VALIDATION,
+  BaseDto
+};
+//# sourceMappingURL=chunk-BKZOLGQW.js.map

package/dist/chunk-BKZOLGQW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/backend/core/global/classes/base-dto.class.ts"],"sourcesContent":["import type { BoundValidator } from '../interfaces/ports/object-validator.port';\n\n/**\n * Sentinel value to skip validation in DTO constructors.\n *\n * Use this when creating a DTO from already-validated data,\n * such as when mapping between layers or in tests.\n *\n * @example\n * ```typescript\n * // Skip validation for already-validated data\n * const dto = new CreateUserInputDto(validatedData, SKIP_DTO_VALIDATION);\n * ```\n */\nexport const SKIP_DTO_VALIDATION = 'skip dto validation' as const;\n\n/**\n * Base class for Data Transfer Objects (DTOs).\n *\n * DTOs are validated data containers used to transfer data between layers.\n * Unlike Value Objects, DTOs are not domain concepts - they are purely\n * for data transfer and validation at system boundaries.\n *\n * Key differences from Value Objects:\n * - **DTOs**: Transfer data between layers (e.g., request/response payloads)\n * - **Value Objects**: Represent domain concepts with behavior (e.g., Email, Money)\n *\n * @typeParam T - The shape of the data being transferred\n *\n * @example\n * ```typescript\n * // Define a DTO with validation\n * class CreateUserInputDto extends BaseDto<{ name: string; email: string }> {\n *   private constructor(data: unknown, validator: BoundValidator<{ name: string; email: string }>) {\n *     super(data, validator);\n *   }\n *\n *   static create(data: unknown): CreateUserInputDto {\n *     return new CreateUserInputDto(data, createUserValidator);\n *   }\n * }\n *\n * // Usage in a controller\n * const dto = CreateUserInputDto.create(request.body);\n * console.log(dto.data.name); // Typed and validated\n * ```\n */\nexport class BaseDto<T> {\n  private readonly _data: T;\n\n  /**\n   * Creates a new DTO instance.\n   *\n   * @param data - The raw data to validate and wrap\n   * @param validator - A bound validator or SKIP_DTO_VALIDATION to bypass\n   * @throws {ObjectValidationError} When validation fails\n   */\n  constructor(data: T, validator: BoundValidator<T> | typeof SKIP_DTO_VALIDATION) {\n    this._data = validator === SKIP_DTO_VALIDATION ? data : validator.validate(data);\n  }\n\n  /**\n   * The validated data payload.\n   *\n   * @returns The validated data of type T\n   */\n  public get data(): T {\n    return this._data;\n  }\n}\n"],"mappings":";AAcO,IAAM,sBAAsB;AAiC5B,IAAM,UAAN,MAAiB;AAAA,EACL;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASjB,YAAY,MAAS,WAA2D;AAC9E,SAAK,QAAQ,cAAc,sBAAsB,OAAO,UAAU,SAAS,IAAI;AAAA,EACjF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAW,OAAU;AACnB,WAAO,KAAK;AAAA,EACd;AACF;","names":[]}

package/dist/chunk-CGZBV6BD.js

@@ -0,0 +1,54 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : { get [name]() {
+    return __privateGet(this, extra);
+  }, set [name](x) {
+    return __privateSet(this, extra, x);
+  } }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => name in x };
+      if (k ^ 3) access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2) access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? void 0 : { get: desc.get, set: desc.set } : target, ctx), done._ = 1;
+    if (k ^ 4 || it === void 0) __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null) __typeError("Object expected");
+    else __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+export {
+  __decoratorStart,
+  __runInitializers,
+  __decorateElement
+};
+//# sourceMappingURL=chunk-CGZBV6BD.js.map

package/dist/chunk-CGZBV6BD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-DDAHJZVK.js

@@ -0,0 +1,258 @@
+import {
+  wrapErrorUnless,
+  wrapErrorUnlessAsync
+} from "./chunk-OKFXZHBC.js";
+import {
+  AccessDeniedError,
+  ControllerError,
+  InvalidRequestError
+} from "./chunk-74IKUOSE.js";
+import {
+  CodedError,
+  ObjectValidationError
+} from "./chunk-MQD5GXMT.js";
+
+// 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/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);
+  }
+}
+
+export {
+  BaseController,
+  GuardedController,
+  defineSystemMetadata,
+  computeRoutePath,
+  isHttpResponse,
+  assertHttpResponse
+};
+//# sourceMappingURL=chunk-DDAHJZVK.js.map

package/dist/chunk-DDAHJZVK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/backend/core/onion-layers/presentation/classes/base-controller.class.ts","../src/backend/core/onion-layers/presentation/classes/guarded-controller.class.ts","../src/backend/core/onion-layers/presentation/interfaces/types/metadata/system-metadata.type.ts","../src/backend/core/onion-layers/presentation/routing/compute-route-path.util.ts","../src/backend/core/onion-layers/presentation/utils/http-response.util.ts"],"sourcesContent":["import type { BaseInboundPort } from '../../app/interfaces/ports/base-inbound.port';\nimport type { BaseDto } from '../../../global/classes/base-dto.class';\nimport { CodedError } from '../../../global/exceptions/coded-error.error';\nimport { ObjectValidationError } from '../../../global/exceptions/object-validation.error';\nimport { wrapErrorUnless, wrapErrorUnlessAsync } from '../../../global/utils/wrap-error.util';\nimport { ControllerError } from '../exceptions/controller.error';\nimport { InvalidRequestError } from '../exceptions/invalid-request.error';\n\n/**\n * Configuration for creating a BaseController instance.\n *\n * All types must be DTOs (extending BaseDto) to ensure validation at every boundary:\n * - TRequestDto: Validated HTTP request (body, headers, params, query)\n * - TResponseDto: Validated HTTP response structure\n * - TInDto: Validated use case input\n * - TOutDto: Validated use case output\n *\n * @typeParam TRequestDto - Validated request DTO from the framework layer\n * @typeParam TResponseDto - Validated response DTO to return to the framework\n * @typeParam TInDto - Input DTO type for the use case\n * @typeParam TOutDto - Output DTO type from the use case\n */\nexport interface BaseControllerConfig<\n  TRequestDto extends BaseDto<unknown>,\n  TResponseDto extends BaseDto<unknown>,\n  TInDto extends BaseDto<unknown>,\n  TOutDto extends BaseDto<unknown>,\n> {\n  /** Maps the validated request DTO to a use case input DTO. */\n  requestMapper: (request: TRequestDto) => TInDto;\n  /** The use case to execute. */\n  useCase: BaseInboundPort<TInDto, TOutDto>;\n  /** Maps the use case output DTO to a validated response DTO. */\n  responseMapper: (output: TOutDto) => TResponseDto;\n}\n\n/**\n * Base controller implementing the request/response pipeline.\n *\n * Orchestrates the flow: `requestDto → mapRequest → executeUseCase → mapResponse → responseDto`\n *\n * All boundaries are validated DTOs:\n * - Input: TRequestDto (validated by framework layer before controller)\n * - Use case input: TInDto (validated by mapRequest)\n * - Use case output: TOutDto (validated by use case)\n * - Output: TResponseDto (validated by mapResponse)\n *\n * Features:\n * - Converts {@link ObjectValidationError} to {@link InvalidRequestError}\n * - Passes through known {@link CodedError} types\n * - Wraps unknown errors in {@link ControllerError}\n *\n * Architecture:\n * - {@link execute} - Public entry point with error wrapping (do not override)\n * - {@link pipeline} - Protected pipeline orchestration (override for custom flow)\n * - {@link mapRequest} - Request-to-input transformation\n * - {@link executeUseCase} - Use case execution\n * - {@link mapResponse} - Output-to-response transformation\n *\n * @typeParam TRequestDto - Validated request DTO from the framework layer\n * @typeParam TResponseDto - Validated response DTO to return to the framework\n * @typeParam TInDto - Input DTO type for the use case\n * @typeParam TOutDto - Output DTO type from the use case\n *\n * @example Basic usage\n * ```typescript\n * const controller = BaseController.create({\n *   requestMapper: (req) => CreateUserInputDto.create(req.data),\n *   useCase: createUserUseCase,\n *   responseMapper: (output) => CreateUserResponseDto.create({ id: output.data.id }),\n * });\n *\n * // Framework layer creates the request DTO\n * const requestDto = CreateUserRequestDto.create(httpRequest);\n * const responseDto = await controller.execute(requestDto);\n * ```\n *\n * @example Custom controller overriding pipeline\n * ```typescript\n * class LoggingController extends BaseController<...> {\n *   protected override async pipeline(input: TRequestDto): Promise<TResponseDto> {\n *     console.log('Request received:', input);\n *     const result = await super.pipeline(input);\n *     console.log('Response:', result);\n *     return result;\n *   }\n * }\n * ```\n *\n * @example Custom controller overriding individual methods\n * ```typescript\n * class CachingController extends BaseController<...> {\n *   private cache = new Map();\n *\n *   protected override async executeUseCase(input: TInDto): Promise<TOutDto> {\n *     const key = JSON.stringify(input.data);\n *     if (this.cache.has(key)) return this.cache.get(key);\n *     const result = await super.executeUseCase(input);\n *     this.cache.set(key, result);\n *     return result;\n *   }\n * }\n * ```\n */\nexport class BaseController<\n  TRequestDto extends BaseDto<unknown>,\n  TResponseDto extends BaseDto<unknown>,\n  TInDto extends BaseDto<unknown>,\n  TOutDto extends BaseDto<unknown>,\n> {\n  /**\n   * Creates a new BaseController instance.\n   *\n   * @param requestMapper - Function to map request DTO to use case input DTO\n   * @param useCase - The use case port to execute\n   * @param responseMapper - Function to map use case output DTO to response DTO\n   */\n  constructor(\n    protected readonly requestMapper: (request: TRequestDto) => TInDto,\n    protected readonly useCase: BaseInboundPort<TInDto, TOutDto>,\n    protected readonly responseMapper: (output: TOutDto) => TResponseDto,\n  ) {}\n\n  /**\n   * Factory method to create a controller from a configuration object.\n   *\n   * @param config - Controller configuration\n   * @returns A new BaseController instance\n   */\n  static create<\n    TRequestDto extends BaseDto<unknown>,\n    TResponseDto extends BaseDto<unknown>,\n    TInDto extends BaseDto<unknown>,\n    TOutDto extends BaseDto<unknown>,\n  >(\n    config: BaseControllerConfig<TRequestDto, TResponseDto, TInDto, TOutDto>,\n  ): BaseController<TRequestDto, TResponseDto, TInDto, TOutDto> {\n    return new BaseController(config.requestMapper, config.useCase, config.responseMapper);\n  }\n\n  /**\n   * Executes the controller pipeline with error wrapping.\n   *\n   * This is the public entry point that ensures consistent error handling.\n   * All errors are wrapped in {@link ControllerError} unless they extend {@link CodedError}.\n   *\n   * **Do not override this method.** Override {@link pipeline} instead for custom pipeline logic.\n   *\n   * @param input - The validated request DTO\n   * @returns Promise resolving to the validated response DTO\n   * @throws {InvalidRequestError} When request mapping/validation fails\n   * @throws {ControllerError} When an unexpected error occurs\n   * @throws {CodedError} When use case throws a known error type\n   */\n  async execute(input: TRequestDto): Promise<TResponseDto> {\n    return wrapErrorUnlessAsync(\n      () => this.pipeline(input),\n      (cause) =>\n        new ControllerError({\n          message: cause instanceof Error ? cause.message : 'Controller execution failed',\n          cause,\n        }),\n      [CodedError],\n    );\n  }\n\n  /**\n   * Runs the controller pipeline.\n   *\n   * Orchestrates: `mapRequest → executeUseCase → mapResponse`\n   *\n   * Override this method to customize the entire pipeline flow, or override\n   * individual protected methods ({@link mapRequest}, {@link executeUseCase},\n   * {@link mapResponse}) for more granular control.\n   *\n   * @param input - The validated request DTO\n   * @returns Promise resolving to the validated response DTO\n   */\n  protected async pipeline(input: TRequestDto): Promise<TResponseDto> {\n    const mappedInput = this.mapRequest(input);\n    const result = await this.executeUseCase(mappedInput);\n    return this.mapResponse(result);\n  }\n\n  /**\n   * Maps the request DTO to a use case input DTO.\n   *\n   * Override to add custom pre-processing, logging, or transformation logic.\n   * The default implementation uses the configured `requestMapper` and converts\n   * {@link ObjectValidationError} to {@link InvalidRequestError}.\n   *\n   * @param input - The validated request DTO\n   * @returns The use case input DTO\n   * @throws {InvalidRequestError} When validation fails\n   * @throws {ControllerError} When mapping fails unexpectedly\n   */\n  protected mapRequest(input: TRequestDto): TInDto {\n    return wrapErrorUnless(\n      () => this.requestMapper(input),\n      (cause) => {\n        if (cause instanceof ObjectValidationError) {\n          return new InvalidRequestError({\n            message: cause.message,\n            cause,\n            validationErrors: cause.validationErrors,\n          });\n        }\n        return new ControllerError({\n          message: cause instanceof Error ? cause.message : 'Request mapping failed',\n          cause,\n        });\n      },\n      [CodedError],\n    );\n  }\n\n  /**\n   * Executes the use case with the mapped input.\n   *\n   * Override to add custom logic around use case execution, such as:\n   * - Logging/tracing\n   * - Caching\n   * - Retry logic\n   * - Multi-use-case orchestration\n   *\n   * @param input - The use case input DTO\n   * @returns Promise resolving to the use case output DTO\n   */\n  protected async executeUseCase(input: TInDto): Promise<TOutDto> {\n    return this.useCase.execute(input);\n  }\n\n  /**\n   * Maps the use case output DTO to a response DTO.\n   *\n   * Override to add custom post-processing, logging, or transformation logic.\n   * The default implementation uses the configured `responseMapper`.\n   *\n   * @param output - The use case output DTO\n   * @returns The response DTO\n   * @throws {ControllerError} When mapping or validation fails\n   */\n  protected mapResponse(output: TOutDto): TResponseDto {\n    return wrapErrorUnless(\n      () => this.responseMapper(output),\n      (cause) =>\n        new ControllerError({\n          message:\n            cause instanceof ObjectValidationError\n              ? 'Response validation failed'\n              : cause instanceof Error\n                ? cause.message\n                : 'Response mapping failed',\n          cause,\n        }),\n      [CodedError],\n    );\n  }\n}\n","import type { AccessGuard } from '../interfaces/types/access-guard.type';\nimport type { AccessGuardResult } from '../interfaces/types/access-guard-result.type';\nimport type { BaseInboundPort } from '../../app/interfaces/ports/base-inbound.port';\nimport type { BaseDto } from '../../../global/classes/base-dto.class';\nimport { BaseController } from './base-controller.class';\nimport { AccessDeniedError } from '../exceptions/access-denied.error';\n\n/**\n * Configuration for creating a GuardedController instance.\n *\n * All types must be DTOs (extending BaseDto) to ensure validation at every boundary.\n *\n * @typeParam TRequestDto - Validated request DTO from the framework layer\n * @typeParam TResponseDto - Validated response DTO to return to the framework\n * @typeParam TInDto - Input DTO type for the use case\n * @typeParam TOutDto - Output DTO type from the use case\n */\nexport interface GuardedControllerConfig<\n  TRequestDto extends BaseDto<unknown>,\n  TResponseDto extends BaseDto<unknown>,\n  TInDto extends BaseDto<unknown>,\n  TOutDto extends BaseDto<unknown>,\n> {\n  /** Maps the validated request DTO to a use case input DTO. */\n  requestMapper: (request: TRequestDto) => TInDto;\n  /** The use case to execute. */\n  useCase: BaseInboundPort<TInDto, TOutDto>;\n  /** Maps the use case output DTO to a validated response DTO. */\n  responseMapper: (output: TOutDto) => TResponseDto;\n  /** Optional access guard; defaults to allowing all requests. */\n  accessGuard?: AccessGuard<TRequestDto>;\n}\n\n/**\n * Creates a type-safe default access guard that allows all requests.\n * @internal\n */\nfunction createAllowAllGuard<T>(): AccessGuard<T> {\n  return async (): Promise<AccessGuardResult> => ({\n    isAllowed: true,\n  });\n}\n\n/**\n * Controller with access control.\n *\n * Extends {@link BaseController} with an access guard that runs before\n * the pipeline. If the guard denies access, an {@link AccessDeniedError}\n * is thrown.\n *\n * All types must be DTOs (extending BaseDto) to ensure validation at every boundary.\n *\n * @typeParam TRequestDto - Validated request DTO from the framework layer\n * @typeParam TResponseDto - Validated response DTO to return to the framework\n * @typeParam TInDto - Input DTO type for the use case\n * @typeParam TOutDto - Output DTO type from the use case\n *\n * @example\n * ```typescript\n * const controller = GuardedController.create({\n *   requestMapper: (req) => UpdateUserInputDto.create(req.data),\n *   useCase: updateUserUseCase,\n *   responseMapper: (output) => UpdateUserResponseDto.create(output.data),\n *   accessGuard: async (req) => ({\n *     isAllowed: req.data.user?.role === 'admin',\n *     reason: 'Admin access required',\n *   }),\n * });\n * ```\n */\nexport class GuardedController<\n  TRequestDto extends BaseDto<unknown>,\n  TResponseDto extends BaseDto<unknown>,\n  TInDto extends BaseDto<unknown>,\n  TOutDto extends BaseDto<unknown>,\n> extends BaseController<TRequestDto, TResponseDto, TInDto, TOutDto> {\n  /** The access guard function for this controller. */\n  protected readonly accessGuard: AccessGuard<TRequestDto>;\n\n  /**\n   * Creates a new GuardedController instance.\n   *\n   * @param requestMapper - Function to map request DTO to use case input DTO\n   * @param useCase - The use case port to execute\n   * @param responseMapper - Function to map use case output DTO to response DTO\n   * @param accessGuard - Optional access guard; defaults to allowing all\n   */\n  constructor(\n    requestMapper: (request: TRequestDto) => TInDto,\n    useCase: BaseInboundPort<TInDto, TOutDto>,\n    responseMapper: (output: TOutDto) => TResponseDto,\n    accessGuard?: AccessGuard<TRequestDto>,\n  ) {\n    super(requestMapper, useCase, responseMapper);\n    this.accessGuard = accessGuard ?? createAllowAllGuard<TRequestDto>();\n  }\n\n  /**\n   * Factory method to create a guarded controller from a configuration object.\n   *\n   * @param config - Controller configuration including optional access guard\n   * @returns A new GuardedController instance\n   */\n  static override create<\n    TRequestDto extends BaseDto<unknown>,\n    TResponseDto extends BaseDto<unknown>,\n    TInDto extends BaseDto<unknown>,\n    TOutDto extends BaseDto<unknown>,\n  >(\n    config: GuardedControllerConfig<TRequestDto, TResponseDto, TInDto, TOutDto>,\n  ): GuardedController<TRequestDto, TResponseDto, TInDto, TOutDto> {\n    return new GuardedController(\n      config.requestMapper,\n      config.useCase,\n      config.responseMapper,\n      config.accessGuard,\n    );\n  }\n\n  /**\n   * Runs the controller pipeline with access control.\n   *\n   * Checks the access guard before executing the pipeline.\n   * If denied, throws {@link AccessDeniedError}.\n   *\n   * @param input - The validated request DTO\n   * @returns Promise resolving to the validated response DTO\n   * @throws {AccessDeniedError} When access guard denies the request\n   */\n  protected override async pipeline(input: TRequestDto): Promise<TResponseDto> {\n    await this.checkAccess(input);\n    return super.pipeline(input);\n  }\n\n  /**\n   * Checks access using the configured guard.\n   *\n   * Override to customize access control logic.\n   *\n   * @param input - The validated request DTO\n   * @throws {AccessDeniedError} When access is denied\n   */\n  protected async checkAccess(input: TRequestDto): Promise<void> {\n    const result = await this.accessGuard(input);\n    if (!result.isAllowed) {\n      throw new AccessDeniedError({\n        message: result.reason ?? 'Access denied',\n      });\n    }\n  }\n}\n","/**\n * System metadata.\n *\n * Top-level metadata for the whole API surface (\"the system\"), sitting above\n * individual services/resources/endpoints.\n *\n * This is intentionally stable and serializable so it can be consumed by tools\n * (OpenAPI generation, docs, code generation).\n */\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// Auth Scheme Types\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/**\n * API Key authentication scheme (header, query, or cookie).\n */\nexport interface ApiKeyAuthScheme {\n  type: 'apiKey';\n  in: 'header' | 'query' | 'cookie';\n  /** Header/query/cookie parameter name, e.g. 'x-api-key' */\n  name: string;\n  description?: string;\n}\n\n/**\n * HTTP Bearer authentication scheme.\n */\nexport interface HttpBearerAuthScheme {\n  type: 'http';\n  scheme: 'bearer';\n  bearerFormat?: string;\n  description?: string;\n}\n\n/**\n * HTTP Basic authentication scheme.\n */\nexport interface HttpBasicAuthScheme {\n  type: 'http';\n  scheme: 'basic';\n  description?: string;\n}\n\n/**\n * Union of all supported authentication schemes.\n */\nexport type AuthScheme = ApiKeyAuthScheme | HttpBearerAuthScheme | HttpBasicAuthScheme;\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// System Metadata Type\n// ═══════════════════════════════════════════════════════════════════════════════\n\nexport interface SystemMetadata {\n  // ═══════════════════════════════════════════════════════════════════════════\n  // IDENTITY (required — routing, logging, code generation)\n  // ═══════════════════════════════════════════════════════════════════════════\n\n  /**\n   * Stable system identifier.\n   *\n   * Recommendation: kebab-case.\n   * Example: `acmp-connector`\n   */\n  id: string;\n\n  /**\n   * Short identifier for compact displays/logging.\n   *\n   * Example: `acmp`\n   */\n  shortId: string;\n\n  /**\n   * Human-readable system name.\n   *\n   * Example: `ACMP Connector`\n   */\n  name: string;\n\n  /**\n   * Human-readable description.\n   */\n  description?: string;\n\n  /**\n   * System/API version (SemVer recommended).\n   *\n   * Example: `1.0.0`\n   */\n  version: string;\n\n  // ═══════════════════════════════════════════════════════════════════════════\n  // DOMAIN (system-specific — servers, auth)\n  // ═══════════════════════════════════════════════════════════════════════════\n\n  /**\n   * Default servers for the API.\n   * Used by OpenAPI generation and client configuration.\n   */\n  servers?: {\n    url: string;\n    description?: string;\n  }[];\n\n  /**\n   * Authentication configuration.\n   */\n  auth?: {\n    /**\n     * Whether endpoints should be considered secure by default.\n     * @default true\n     */\n    secureByDefault?: boolean;\n\n    /**\n     * Available authentication schemes.\n     *\n     * Keyed by scheme name (must be unique within the system).\n     * Example: `{ apiKeyAuth: { type: 'apiKey', in: 'header', name: 'x-api-key' } }`\n     */\n    schemes: Record<string, AuthScheme>;\n\n    /**\n     * Default security requirements (applies to all secure endpoints).\n     *\n     * OpenAPI semantics:\n     * - Array is OR (any requirement can satisfy)\n     * - Object is AND (all schemes required together)\n     *\n     * Example: `[{ apiKeyAuth: [] }]`\n     */\n    defaultSecurity?: Record<string, string[]>[];\n  };\n\n  // ═══════════════════════════════════════════════════════════════════════════\n  // OPENAPI (optional — documentation generation)\n  // Override pattern: openApi.xxx overrides base xxx\n  // ═══════════════════════════════════════════════════════════════════════════\n\n  /**\n   * OpenAPI-specific overrides for global spec generation.\n   */\n  openApi?: {\n    /**\n     * OpenAPI info.title.\n     * Overrides `name` if set.\n     */\n    title?: string;\n\n    /**\n     * OpenAPI info.description.\n     * Overrides `description` if set.\n     */\n    description?: string;\n\n    /**\n     * OpenAPI info.termsOfService URL.\n     */\n    termsOfService?: string;\n\n    /**\n     * OpenAPI info.contact.\n     */\n    contact?: {\n      name?: string;\n      url?: string;\n      email?: string;\n    };\n\n    /**\n     * OpenAPI info.license.\n     */\n    license?: {\n      name: string;\n      url?: string;\n    };\n  };\n}\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// Utility Types\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/**\n * Extracts the scheme names (keys) from a SystemMetadata constant.\n *\n * @example\n * const systemMeta = { auth: { schemes: { apiKeyAuth: {...}, bearerAuth: {...} } } } as const;\n * type Names = SchemeNamesOf<typeof systemMeta>; // 'apiKeyAuth' | 'bearerAuth'\n */\nexport type SchemeNamesOf<TSystem> = TSystem extends {\n  auth: { schemes: infer S };\n}\n  ? keyof S & string\n  : never;\n\n/**\n * Creates a typed OpenAPI security requirement array from scheme names.\n *\n * @example\n * type Req = SecurityRequirementOf<'apiKeyAuth' | 'bearerAuth'>;\n * // Array<Partial<Record<'apiKeyAuth' | 'bearerAuth', string[]>>>\n */\nexport type SecurityRequirementOf<TSchemeNames extends string> = Partial<\n  Record<TSchemeNames, string[]>\n>[];\n\n// ═══════════════════════════════════════════════════════════════════════════════\n// Helper Function\n// ═══════════════════════════════════════════════════════════════════════════════\n\n/**\n * Input type for defineSystemMetadata helper (with generic auth).\n */\ntype SystemMetadataInput<TSchemeNames extends string> = Omit<SystemMetadata, 'auth'> & {\n  auth?: {\n    secureByDefault?: boolean;\n    schemes: Record<TSchemeNames, AuthScheme>;\n    defaultSecurity?: Partial<Record<TSchemeNames, string[]>>[];\n  };\n};\n\n/**\n * Defines system metadata with fully-typed `defaultSecurity`.\n *\n * Infers scheme names from the `schemes` object and validates that\n * `defaultSecurity` only references existing scheme names.\n *\n * @example\n * export const systemMetadata = defineSystemMetadata({\n *   id: 'my-api',\n *   shortId: 'api',\n *   name: 'My API',\n *   version: '1.0.0',\n *   auth: {\n *     schemes: {\n *       apiKeyAuth: { type: 'apiKey', in: 'header', name: 'x-api-key' },\n *     },\n *     defaultSecurity: [{ apiKeyAuth: [] }],  // ✅ Valid\n *     // defaultSecurity: [{ typoAuth: [] }], // ❌ TypeScript error!\n *   },\n * });\n */\nexport function defineSystemMetadata<const TSchemeNames extends string>(\n  metadata: SystemMetadataInput<TSchemeNames>,\n): SystemMetadataInput<TSchemeNames> & SystemMetadata {\n  return metadata as SystemMetadataInput<TSchemeNames> & SystemMetadata;\n}\n","import type { HttpEndpointMetadata } from '../interfaces/types/metadata/http-endpoint-metadata.type';\nimport type { ResourceMetadata } from '../interfaces/types/metadata/resource-metadata.type';\nimport type { ServiceMetadata } from '../interfaces/types/metadata/service-metadata.type';\n\n/**\n * Normalizes a path segment by removing leading/trailing slashes.\n */\nfunction trimSlashes(segment: string): string {\n  return segment.replace(/^\\/+|\\/+$/g, '');\n}\n\n/**\n * Computes the full route path from service, resource, and endpoint metadata.\n *\n * Handles path normalization:\n * - Ensures leading slash\n * - Joins segments with single slashes\n * - Removes trailing slash (except for root)\n *\n * @example\n * ```typescript\n * computeRoutePath(\n *   { basePath: '/user-service' },\n *   { path: '/users' },\n *   { path: '/{id}' }\n * ); // => '/user-service/users/{id}'\n * ```\n */\nexport function computeRoutePath(\n  service: Pick<ServiceMetadata, 'basePath'>,\n  resource: Pick<ResourceMetadata, 'path'>,\n  endpoint: Pick<HttpEndpointMetadata, 'path'>,\n): string {\n  const segments = [service.basePath, resource.path, endpoint.path]\n    .map(trimSlashes)\n    .filter((s) => s.length > 0);\n\n  if (segments.length === 0) {\n    return '/';\n  }\n\n  return '/' + segments.join('/');\n}\n","import type { HttpResponse } from '../interfaces/types/http/http-response';\n\n/**\n * Type guard to validate that a value is a valid HttpResponse.\n *\n * Checks that the value has the required `statusCode` property as a number.\n * This is used to validate controller outputs before passing to response mappers.\n *\n * @param value - The value to check\n * @returns True if the value is a valid HttpResponse\n *\n * @example\n * ```typescript\n * const output = controller.execute(input);\n * if (!isHttpResponse(output)) {\n *   throw new Error('Controller must return an HttpResponse');\n * }\n * ```\n */\nexport function isHttpResponse(value: unknown): value is HttpResponse {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'statusCode' in value &&\n    typeof (value as { statusCode: unknown }).statusCode === 'number'\n  );\n}\n\n/**\n * Asserts that a value is a valid HttpResponse.\n *\n * Throws a descriptive error if the value is not a valid HttpResponse,\n * making it easier to debug controller output issues.\n *\n * @param value - The value to validate\n * @param context - Optional context for the error message (e.g., 'mapOutput')\n * @throws Error if the value is not a valid HttpResponse\n *\n * @example\n * ```typescript\n * const output = controller.execute(input);\n * assertHttpResponse(output, 'controller output');\n * // Now TypeScript knows output is HttpResponse\n * ```\n */\nexport function assertHttpResponse(\n  value: unknown,\n  context = 'value',\n): asserts value is HttpResponse {\n  if (!isHttpResponse(value)) {\n    const actualType = value === null ? 'null' : value === undefined ? 'undefined' : typeof value;\n    const hasStatusCode = typeof value === 'object' && value !== null && 'statusCode' in value;\n\n    let message = `Expected ${context} to be an HttpResponse with a numeric statusCode, `;\n\n    if (hasStatusCode) {\n      const statusCodeType = typeof (value as { statusCode: unknown })['statusCode'];\n      message += `but statusCode was ${statusCodeType}`;\n    } else {\n      message += `but got ${actualType}`;\n    }\n\n    throw new Error(message);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwGO,IAAM,iBAAN,MAAM,gBAKX;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,YACqB,eACA,SACA,gBACnB;AAHmB;AACA;AACA;AAAA,EAClB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQH,OAAO,OAML,QAC4D;AAC5D,WAAO,IAAI,gBAAe,OAAO,eAAe,OAAO,SAAS,OAAO,cAAc;AAAA,EACvF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgBA,MAAM,QAAQ,OAA2C;AACvD,WAAO;AAAA,MACL,MAAM,KAAK,SAAS,KAAK;AAAA,MACzB,CAAC,UACC,IAAI,gBAAgB;AAAA,QAClB,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,QAClD;AAAA,MACF,CAAC;AAAA,MACH,CAAC,UAAU;AAAA,IACb;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,MAAgB,SAAS,OAA2C;AAClE,UAAM,cAAc,KAAK,WAAW,KAAK;AACzC,UAAM,SAAS,MAAM,KAAK,eAAe,WAAW;AACpD,WAAO,KAAK,YAAY,MAAM;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcU,WAAW,OAA4B;AAC/C,WAAO;AAAA,MACL,MAAM,KAAK,cAAc,KAAK;AAAA,MAC9B,CAAC,UAAU;AACT,YAAI,iBAAiB,uBAAuB;AAC1C,iBAAO,IAAI,oBAAoB;AAAA,YAC7B,SAAS,MAAM;AAAA,YACf;AAAA,YACA,kBAAkB,MAAM;AAAA,UAC1B,CAAC;AAAA,QACH;AACA,eAAO,IAAI,gBAAgB;AAAA,UACzB,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,UAClD;AAAA,QACF,CAAC;AAAA,MACH;AAAA,MACA,CAAC,UAAU;AAAA,IACb;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,MAAgB,eAAe,OAAiC;AAC9D,WAAO,KAAK,QAAQ,QAAQ,KAAK;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYU,YAAY,QAA+B;AACnD,WAAO;AAAA,MACL,MAAM,KAAK,eAAe,MAAM;AAAA,MAChC,CAAC,UACC,IAAI,gBAAgB;AAAA,QAClB,SACE,iBAAiB,wBACb,+BACA,iBAAiB,QACf,MAAM,UACN;AAAA,QACR;AAAA,MACF,CAAC;AAAA,MACH,CAAC,UAAU;AAAA,IACb;AAAA,EACF;AACF;;;AC7NA,SAAS,sBAAyC;AAChD,SAAO,aAAyC;AAAA,IAC9C,WAAW;AAAA,EACb;AACF;AA6BO,IAAM,oBAAN,MAAM,2BAKH,eAA2D;AAAA;AAAA,EAEhD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUnB,YACE,eACA,SACA,gBACA,aACA;AACA,UAAM,eAAe,SAAS,cAAc;AAC5C,SAAK,cAAc,eAAe,oBAAiC;AAAA,EACrE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAgB,OAMd,QAC+D;AAC/D,WAAO,IAAI;AAAA,MACT,OAAO;AAAA,MACP,OAAO;AAAA,MACP,OAAO;AAAA,MACP,OAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAyB,SAAS,OAA2C;AAC3E,UAAM,KAAK,YAAY,KAAK;AAC5B,WAAO,MAAM,SAAS,KAAK;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAgB,YAAY,OAAmC;AAC7D,UAAM,SAAS,MAAM,KAAK,YAAY,KAAK;AAC3C,QAAI,CAAC,OAAO,WAAW;AACrB,YAAM,IAAI,kBAAkB;AAAA,QAC1B,SAAS,OAAO,UAAU;AAAA,MAC5B,CAAC;AAAA,IACH;AAAA,EACF;AACF;;;AC8FO,SAAS,qBACd,UACoD;AACpD,SAAO;AACT;;;ACjPA,SAAS,YAAY,SAAyB;AAC5C,SAAO,QAAQ,QAAQ,cAAc,EAAE;AACzC;AAmBO,SAAS,iBACd,SACA,UACA,UACQ;AACR,QAAM,WAAW,CAAC,QAAQ,UAAU,SAAS,MAAM,SAAS,IAAI,EAC7D,IAAI,WAAW,EACf,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC;AAE7B,MAAI,SAAS,WAAW,GAAG;AACzB,WAAO;AAAA,EACT;AAEA,SAAO,MAAM,SAAS,KAAK,GAAG;AAChC;;;ACvBO,SAAS,eAAe,OAAuC;AACpE,SACE,OAAO,UAAU,YACjB,UAAU,QACV,gBAAgB,SAChB,OAAQ,MAAkC,eAAe;AAE7D;AAmBO,SAAS,mBACd,OACA,UAAU,SACqB;AAC/B,MAAI,CAAC,eAAe,KAAK,GAAG;AAC1B,UAAM,aAAa,UAAU,OAAO,SAAS,UAAU,SAAY,cAAc,OAAO;AACxF,UAAM,gBAAgB,OAAO,UAAU,YAAY,UAAU,QAAQ,gBAAgB;AAErF,QAAI,UAAU,YAAY,OAAO;AAEjC,QAAI,eAAe;AACjB,YAAM,iBAAiB,OAAQ,MAAkC,YAAY;AAC7E,iBAAW,sBAAsB,cAAc;AAAA,IACjD,OAAO;AACL,iBAAW,WAAW,UAAU;AAAA,IAClC;AAEA,UAAM,IAAI,MAAM,OAAO;AAAA,EACzB;AACF;","names":[]}