@cosmneo/onion-lasagna 0.1.0

package/dist/backend/core/global.cjs

@@ -0,0 +1,283 @@
+"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/global/index.ts
+var global_exports = {};
+__export(global_exports, {
+  BaseDto: () => BaseDto,
+  CodedError: () => CodedError,
+  ErrorCodes: () => ErrorCodes,
+  ObjectValidationError: () => ObjectValidationError,
+  SKIP_DTO_VALIDATION: () => SKIP_DTO_VALIDATION,
+  fieldChanged: () => fieldChanged,
+  wrapError: () => wrapError,
+  wrapErrorAsync: () => wrapErrorAsync,
+  wrapErrorUnless: () => wrapErrorUnless,
+  wrapErrorUnlessAsync: () => wrapErrorUnlessAsync
+});
+module.exports = __toCommonJS(global_exports);
+
+// 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;
+  }
+};
+
+// 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/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/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/field-changed.util.ts
+function fieldChanged({
+  value,
+  newValue,
+  partialUpdate = true
+}) {
+  if (partialUpdate && newValue === void 0) return false;
+  return value !== newValue;
+}
+
+// src/backend/core/global/utils/wrap-error.util.ts
+function wrapError(fn, errorFactory) {
+  try {
+    return fn();
+  } catch (error) {
+    throw errorFactory(error);
+  }
+}
+async function wrapErrorAsync(fn, errorFactory) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw errorFactory(error);
+  }
+}
+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);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseDto,
+  CodedError,
+  ErrorCodes,
+  ObjectValidationError,
+  SKIP_DTO_VALIDATION,
+  fieldChanged,
+  wrapError,
+  wrapErrorAsync,
+  wrapErrorUnless,
+  wrapErrorUnlessAsync
+});
+//# sourceMappingURL=global.cjs.map

package/dist/backend/core/global.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/backend/core/global/index.ts","../../../src/backend/core/global/classes/base-dto.class.ts","../../../src/backend/core/global/exceptions/error-codes.const.ts","../../../src/backend/core/global/exceptions/coded-error.error.ts","../../../src/backend/core/global/exceptions/object-validation.error.ts","../../../src/backend/core/global/utils/field-changed.util.ts","../../../src/backend/core/global/utils/wrap-error.util.ts"],"sourcesContent":["export * from './classes';\nexport * from './exceptions';\nexport * from './interfaces';\nexport * from './utils';\n","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","/**\n * Centralized registry of all error codes used across the application.\n *\n * Error codes are grouped by architectural layer to maintain clear boundaries\n * and make it easy to identify where an error originated.\n *\n * @example Using error codes in custom errors\n * ```typescript\n * import { ErrorCodes } from '@cosmneo/onion-lasagna/backend/core/global';\n *\n * throw new NotFoundError({\n *   message: 'User not found',\n *   code: ErrorCodes.App.NOT_FOUND,\n * });\n * ```\n *\n * @example Checking error codes programmatically\n * ```typescript\n * if (error.code === ErrorCodes.App.NOT_FOUND) {\n *   // Handle not found case\n * }\n * ```\n */\nexport const ErrorCodes = {\n  /**\n   * Domain layer error codes.\n   * Used for business rule violations and invariant failures.\n   */\n  Domain: {\n    /** Generic domain error */\n    DOMAIN_ERROR: 'DOMAIN_ERROR',\n    /** Business invariant was violated */\n    INVARIANT_VIOLATION: 'INVARIANT_VIOLATION',\n    /** Aggregate was partially loaded (missing required relations) */\n    PARTIAL_LOAD: 'PARTIAL_LOAD',\n  },\n\n  /**\n   * Application layer (use case) error codes.\n   * Used for orchestration failures and business operation errors.\n   */\n  App: {\n    /** Generic use case error */\n    USE_CASE_ERROR: 'USE_CASE_ERROR',\n    /** Requested resource was not found */\n    NOT_FOUND: 'NOT_FOUND',\n    /** Resource state conflict (e.g., duplicate, already exists) */\n    CONFLICT: 'CONFLICT',\n    /** Request is valid but cannot be processed due to business rules */\n    UNPROCESSABLE: 'UNPROCESSABLE',\n  },\n\n  /**\n   * Infrastructure layer error codes.\n   * Used for data access, external services, and I/O failures.\n   */\n  Infra: {\n    /** Generic infrastructure error */\n    INFRA_ERROR: 'INFRA_ERROR',\n    /** Database operation failed */\n    DB_ERROR: 'DB_ERROR',\n    /** Network connectivity or communication error */\n    NETWORK_ERROR: 'NETWORK_ERROR',\n    /** Operation timed out */\n    TIMEOUT_ERROR: 'TIMEOUT_ERROR',\n    /** External/third-party service error */\n    EXTERNAL_SERVICE_ERROR: 'EXTERNAL_SERVICE_ERROR',\n  },\n\n  /**\n   * Presentation layer error codes.\n   * Used for controller, request handling, and authorization errors.\n   */\n  Presentation: {\n    /** Generic controller error */\n    CONTROLLER_ERROR: 'CONTROLLER_ERROR',\n    /** Request denied due to authorization failure */\n    ACCESS_DENIED: 'ACCESS_DENIED',\n    /** Request validation failed (malformed input) */\n    INVALID_REQUEST: 'INVALID_REQUEST',\n  },\n\n  /**\n   * Global/cross-cutting error codes.\n   * Used for validation and other cross-layer concerns.\n   */\n  Global: {\n    /** Object/schema validation failed */\n    OBJECT_VALIDATION_ERROR: 'OBJECT_VALIDATION_ERROR',\n  },\n} as const;\n\n/**\n * Type representing all possible domain error codes.\n */\nexport type DomainErrorCode = (typeof ErrorCodes.Domain)[keyof typeof ErrorCodes.Domain];\n\n/**\n * Type representing all possible application error codes.\n */\nexport type AppErrorCode = (typeof ErrorCodes.App)[keyof typeof ErrorCodes.App];\n\n/**\n * Type representing all possible infrastructure error codes.\n */\nexport type InfraErrorCode = (typeof ErrorCodes.Infra)[keyof typeof ErrorCodes.Infra];\n\n/**\n * Type representing all possible presentation error codes.\n */\nexport type PresentationErrorCode =\n  (typeof ErrorCodes.Presentation)[keyof typeof ErrorCodes.Presentation];\n\n/**\n * Type representing all possible global error codes.\n */\nexport type GlobalErrorCode = (typeof ErrorCodes.Global)[keyof typeof ErrorCodes.Global];\n\n/**\n * Union type of all error codes across all layers.\n *\n * Use this when you need to accept any valid error code.\n *\n * @example\n * ```typescript\n * function logError(code: ErrorCode, message: string) {\n *   console.error(`[${code}] ${message}`);\n * }\n * ```\n */\nexport type ErrorCode =\n  | DomainErrorCode\n  | AppErrorCode\n  | InfraErrorCode\n  | PresentationErrorCode\n  | GlobalErrorCode;\n","import type { ErrorCode } from './error-codes.const';\n\n/**\n * Base error class for all application errors with a machine-readable code.\n *\n * Abstract class that extends the native `Error` with:\n * - A `code` property for programmatic error handling\n * - Optional `cause` for error chaining (ES2022 compatible)\n * - A `fromError` static factory pattern for error transformation\n *\n * **Why abstract:** Prevents non-declarative error usage. All errors must\n * be explicitly defined as subclasses to ensure consistent error taxonomy.\n *\n * @example Subclass implementation\n * ```typescript\n * class DbError extends InfraError {\n *   static override fromError(cause: unknown): DbError {\n *     return new DbError({\n *       message: cause instanceof Error ? cause.message : 'Database error',\n *       cause,\n *     });\n *   }\n * }\n * ```\n *\n * @example Usage with wrapErrorAsync\n * ```typescript\n * await wrapErrorAsync(\n *   () => this.db.query(...),\n *   DbError.fromError,\n * );\n * ```\n */\nexport abstract class CodedError extends Error {\n  /** Machine-readable error code for programmatic handling. */\n  public readonly code: ErrorCode | string;\n\n  /**\n   * Creates a new CodedError instance.\n   *\n   * @param options - Error configuration\n   * @param options.message - Human-readable error message\n   * @param options.code - Machine-readable error code from ErrorCodes registry or custom string\n   * @param options.cause - Optional underlying error that caused this error\n   */\n  constructor({\n    message,\n    code,\n    cause,\n  }: {\n    message: string;\n    code: ErrorCode | string;\n    cause?: unknown;\n  }) {\n    super(message);\n    this.name = this.constructor.name;\n    this.code = code;\n    if (cause !== undefined) {\n      Object.defineProperty(this, 'cause', {\n        value: cause,\n        writable: false,\n        enumerable: false,\n        configurable: true,\n      });\n    }\n  }\n\n  /**\n   * Factory method to create a typed error from a caught error.\n   *\n   * Subclasses should override this to provide proper error transformation.\n   * Designed for use with {@link wrapErrorAsync} and {@link wrapError}.\n   *\n   * @param _cause - The original caught error\n   * @returns A new CodedError instance\n   * @throws {Error} If not overridden by subclass\n   *\n   * @example\n   * ```typescript\n   * class NotFoundError extends UseCaseError {\n   *   static override fromError(cause: unknown): NotFoundError {\n   *     return new NotFoundError({\n   *       message: 'Resource not found',\n   *       cause,\n   *     });\n   *   }\n   * }\n   * ```\n   */\n  static fromError(_cause: unknown): CodedError {\n    throw new Error(`${this.name}.fromError() must be implemented by subclass`);\n  }\n}\n","import { CodedError } from './coded-error.error';\nimport { ErrorCodes, type GlobalErrorCode } from './error-codes.const';\nimport type { ValidationError } from '../interfaces/types/validation-error.type';\n\n/**\n * Error thrown when object validation fails.\n *\n * Contains structured validation errors with field paths and messages,\n * making it easy to report specific validation failures to clients.\n * Thrown by all validator implementations (Zod, ArkType, TypeBox, Valibot).\n *\n * **Flow:**\n * 1. Validator throws `ObjectValidationError` with field-level errors\n * 2. Controller catches and converts to {@link InvalidRequestError}\n * 3. HTTP layer maps to 400 Bad Request with error details\n *\n * @example\n * ```typescript\n * try {\n *   const dto = CreateUserDto.create(invalidData);\n * } catch (error) {\n *   if (error instanceof ObjectValidationError) {\n *     console.log(error.validationErrors);\n *     // [\n *     //   { field: 'email', message: 'Invalid email format' },\n *     //   { field: 'age', message: 'Must be a positive number' }\n *     // ]\n *   }\n * }\n * ```\n */\nexport class ObjectValidationError extends CodedError {\n  /**\n   * Array of field-level validation errors.\n   *\n   * Each entry contains:\n   * - `field`: Dot-notation path to the invalid field (e.g., 'user.email')\n   * - `message`: Human-readable validation failure message\n   */\n  validationErrors: ValidationError[];\n\n  /**\n   * Creates a new ObjectValidationError instance.\n   *\n   * @param options - Error configuration\n   * @param options.message - Human-readable summary message\n   * @param options.code - Machine-readable error code (default: 'OBJECT_VALIDATION_ERROR')\n   * @param options.cause - Optional underlying error from validation library\n   * @param options.validationErrors - Array of field-level validation errors\n   */\n  constructor({\n    message,\n    code = ErrorCodes.Global.OBJECT_VALIDATION_ERROR,\n    cause,\n    validationErrors,\n  }: {\n    message: string;\n    code?: GlobalErrorCode | string;\n    cause?: unknown;\n    validationErrors: ValidationError[];\n  }) {\n    super({ message, code, cause });\n    this.validationErrors = validationErrors;\n  }\n\n  /**\n   * Creates an ObjectValidationError from a caught error.\n   *\n   * @param cause - The original caught error\n   * @returns A new ObjectValidationError instance with the cause attached\n   */\n  static override fromError(cause: unknown): ObjectValidationError {\n    return new ObjectValidationError({\n      message: cause instanceof Error ? cause.message : 'Validation failed',\n      cause,\n      validationErrors: [],\n    });\n  }\n}\n","/**\n * Checks if a field has changed by comparing the current value with a new value.\n *\n * Useful for detecting changes in update operations, supporting both partial\n * and full update semantics.\n *\n * **Modes:**\n * - **Partial update** (default): `undefined` means \"keep existing value\" (no change)\n * - **Full update**: `undefined` means \"set to undefined\" (is a change if value !== undefined)\n *\n * **Limitation:** Uses strict equality (`!==`) for comparison, which only works\n * correctly for primitives and reference equality. For objects or arrays, this\n * compares references, not content. Two objects with identical content but\n * different references will be considered \"changed\".\n *\n * For complex objects, either:\n * - Compare by a unique identifier (e.g., `value.id !== newValue?.id`)\n * - Use value objects with `.equals()` methods\n * - Implement deep equality checking in your update logic\n *\n * @typeParam T - The type of the field being compared\n * @param options - Comparison options\n * @param options.value - The current field value\n * @param options.newValue - The incoming value (may be undefined)\n * @param options.partialUpdate - Whether to use partial update semantics (default: true)\n * @returns `true` if the field has changed, `false` otherwise\n *\n * @example Partial update (PATCH semantics)\n * ```typescript\n * // undefined means \"don't change\"\n * fieldChanged({ value: 'John', newValue: undefined }); // false\n * fieldChanged({ value: 'John', newValue: 'Jane' });    // true\n * fieldChanged({ value: 'John', newValue: 'John' });    // false\n * ```\n *\n * @example Full update (PUT semantics)\n * ```typescript\n * // undefined means \"set to undefined\"\n * fieldChanged({ value: 'John', newValue: undefined, partialUpdate: false }); // true\n * ```\n *\n * @example Object comparison (reference-based)\n * ```typescript\n * const obj1 = { name: 'John' };\n * const obj2 = { name: 'John' };\n * fieldChanged({ value: obj1, newValue: obj2 });   // true (different references)\n * fieldChanged({ value: obj1, newValue: obj1 });   // false (same reference)\n * ```\n */\nexport function fieldChanged<T>({\n  value,\n  newValue,\n  partialUpdate = true,\n}: {\n  value: T;\n  newValue: T | undefined;\n  partialUpdate?: boolean;\n}): boolean {\n  if (partialUpdate && newValue === undefined) return false;\n  // For full updates, undefined means \"set to undefined\" which is a change if value !== undefined\n  return value !== newValue;\n}\n","/**\n * Error wrapping utilities for boundary error handling.\n *\n * Provides functions to wrap code execution with error transformation,\n * converting caught errors into typed Error instances.\n * Useful at layer boundaries (infra, use case, controller) to normalize errors.\n *\n * @example Wrapping async database calls\n * ```typescript\n * const user = await wrapErrorAsync(\n *   () => this.db.query('SELECT * FROM users WHERE id = ?', [id]),\n *   (cause) => new DbError({ message: 'Failed to fetch user', cause }),\n * );\n * ```\n *\n * @example Wrapping sync operations\n * ```typescript\n * const parsed = wrapError(\n *   () => JSON.parse(data),\n *   (cause) => new InvariantViolationError({\n *     message: 'Invalid JSON format',\n *     cause,\n *   }),\n * );\n * ```\n *\n * @module\n */\n\n/**\n * Factory function that creates an Error from a caught error.\n *\n * @typeParam E - The specific Error subclass to create\n * @param cause - The original caught error\n * @returns A new Error instance\n */\nexport type ErrorFactory<E extends Error> = (cause: unknown) => E;\n\n/**\n * Wraps a synchronous function with error transformation.\n *\n * Executes the provided function and catches any thrown errors,\n * transforming them using the error factory.\n *\n * @typeParam T - The return type of the wrapped function\n * @typeParam E - The Error subclass to throw on error\n * @param fn - The function to execute\n * @param errorFactory - Factory to create the typed error from the caught error\n * @returns The result of the function if successful\n * @throws {E} The transformed error if the function throws\n *\n * @example\n * ```typescript\n * const config = wrapError(\n *   () => JSON.parse(configString),\n *   (cause) => new InvariantViolationError({\n *     message: 'Invalid configuration format',\n *     code: 'CONFIG_PARSE_ERROR',\n *     cause,\n *   }),\n * );\n * ```\n */\nexport function wrapError<T, E extends Error>(fn: () => T, errorFactory: ErrorFactory<E>): T {\n  try {\n    return fn();\n  } catch (error) {\n    throw errorFactory(error);\n  }\n}\n\n/**\n * Wraps an asynchronous function with error transformation.\n *\n * Executes the provided async function and catches any thrown errors,\n * transforming them using the error factory.\n *\n * @typeParam T - The return type of the wrapped function\n * @typeParam E - The Error subclass to throw on error\n * @param fn - The async function to execute\n * @param errorFactory - Factory to create the typed error from the caught error\n * @returns A promise resolving to the result if successful\n * @throws {E} The transformed error if the function throws\n *\n * @example Repository usage\n * ```typescript\n * async findById(id: string): Promise<User | null> {\n *   return wrapErrorAsync(\n *     () => this.db.users.findUnique({ where: { id } }),\n *     (cause) => new DbError({\n *       message: `Failed to find user by ID: ${id}`,\n *       cause,\n *     }),\n *   );\n * }\n * ```\n *\n * @example External service usage\n * ```typescript\n * async sendEmail(to: string, body: string): Promise<void> {\n *   await wrapErrorAsync(\n *     () => this.emailClient.send({ to, body }),\n *     (cause) => new ExternalServiceError({\n *       message: 'Email delivery failed',\n *       code: 'EMAIL_SEND_FAILED',\n *       cause,\n *     }),\n *   );\n * }\n * ```\n */\nexport async function wrapErrorAsync<T, E extends Error>(\n  fn: () => Promise<T>,\n  errorFactory: ErrorFactory<E>,\n): Promise<T> {\n  try {\n    return await fn();\n  } catch (error) {\n    throw errorFactory(error);\n  }\n}\n\n/**\n * Constructor type for error classes (including abstract classes).\n *\n * Used to specify error types that should pass through without transformation.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type ErrorConstructor = abstract new (...args: any[]) => Error;\n\n/**\n * Wraps a synchronous function with conditional error transformation.\n *\n * Executes the provided function and catches any thrown errors.\n * Errors matching any of the passthrough types are re-thrown as-is.\n * All other errors are transformed using the error factory.\n *\n * @typeParam T - The return type of the wrapped function\n * @typeParam E - The Error subclass to throw for unknown errors\n * @param fn - The function to execute\n * @param errorFactory - Factory to create the typed error from unknown errors\n * @param passthroughTypes - Array of error classes to re-throw without transformation\n * @returns The result of the function if successful\n * @throws The original error if it matches a passthrough type\n * @throws {E} The transformed error for unknown error types\n *\n * @example Controller boundary\n * ```typescript\n * const result = wrapErrorUnless(\n *   () => this.requestMapper(input),\n *   (cause) => new ControllerError({ message: 'Mapping failed', cause }),\n *   [CodedError],\n * );\n * ```\n */\nexport function wrapErrorUnless<T, E extends Error>(\n  fn: () => T,\n  errorFactory: ErrorFactory<E>,\n  passthroughTypes: ErrorConstructor[],\n): T {\n  try {\n    return fn();\n  } catch (error) {\n    if (passthroughTypes.some((Type) => error instanceof Type)) {\n      throw error;\n    }\n    throw errorFactory(error);\n  }\n}\n\n/**\n * Wraps an asynchronous function with conditional error transformation.\n *\n * Executes the provided async function and catches any thrown errors.\n * Errors matching any of the passthrough types are re-thrown as-is.\n * All other errors are transformed using the error factory.\n *\n * @typeParam T - The return type of the wrapped function\n * @typeParam E - The Error subclass to throw for unknown errors\n * @param fn - The async function to execute\n * @param errorFactory - Factory to create the typed error from unknown errors\n * @param passthroughTypes - Array of error classes to re-throw without transformation\n * @returns A promise resolving to the result if successful\n * @throws The original error if it matches a passthrough type\n * @throws {E} The transformed error for unknown error types\n *\n * @example Use case boundary\n * ```typescript\n * return wrapErrorUnlessAsync(\n *   () => this.handle(input),\n *   (cause) => new UseCaseError({ message: 'Unexpected error', cause }),\n *   [ObjectValidationError, UseCaseError, DomainError, InfraError],\n * );\n * ```\n *\n * @example Controller boundary\n * ```typescript\n * return wrapErrorUnlessAsync(\n *   async () => {\n *     const result = await this.useCase.execute(input);\n *     return this.responseMapper(result);\n *   },\n *   (cause) => new ControllerError({ message: 'Controller failed', cause }),\n *   [CodedError],\n * );\n * ```\n */\nexport async function wrapErrorUnlessAsync<T, E extends Error>(\n  fn: () => Promise<T>,\n  errorFactory: ErrorFactory<E>,\n  passthroughTypes: ErrorConstructor[],\n): Promise<T> {\n  try {\n    return await fn();\n  } catch (error) {\n    if (passthroughTypes.some((Type) => error instanceof Type)) {\n      throw error;\n    }\n    throw errorFactory(error);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACcO,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;;;AC9CO,IAAM,aAAa;AAAA;AAAA;AAAA;AAAA;AAAA,EAKxB,QAAQ;AAAA;AAAA,IAEN,cAAc;AAAA;AAAA,IAEd,qBAAqB;AAAA;AAAA,IAErB,cAAc;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAK;AAAA;AAAA,IAEH,gBAAgB;AAAA;AAAA,IAEhB,WAAW;AAAA;AAAA,IAEX,UAAU;AAAA;AAAA,IAEV,eAAe;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO;AAAA;AAAA,IAEL,aAAa;AAAA;AAAA,IAEb,UAAU;AAAA;AAAA,IAEV,eAAe;AAAA;AAAA,IAEf,eAAe;AAAA;AAAA,IAEf,wBAAwB;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,cAAc;AAAA;AAAA,IAEZ,kBAAkB;AAAA;AAAA,IAElB,eAAe;AAAA;AAAA,IAEf,iBAAiB;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,QAAQ;AAAA;AAAA,IAEN,yBAAyB;AAAA,EAC3B;AACF;;;ACzDO,IAAe,aAAf,cAAkC,MAAM;AAAA;AAAA,EAE7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUhB,YAAY;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,EACF,GAIG;AACD,UAAM,OAAO;AACb,SAAK,OAAO,KAAK,YAAY;AAC7B,SAAK,OAAO;AACZ,QAAI,UAAU,QAAW;AACvB,aAAO,eAAe,MAAM,SAAS;AAAA,QACnC,OAAO;AAAA,QACP,UAAU;AAAA,QACV,YAAY;AAAA,QACZ,cAAc;AAAA,MAChB,CAAC;AAAA,IACH;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBA,OAAO,UAAU,QAA6B;AAC5C,UAAM,IAAI,MAAM,GAAG,KAAK,IAAI,8CAA8C;AAAA,EAC5E;AACF;;;AC7DO,IAAM,wBAAN,MAAM,+BAA8B,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQpD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,YAAY;AAAA,IACV;AAAA,IACA,OAAO,WAAW,OAAO;AAAA,IACzB;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,OAAuC;AAC/D,WAAO,IAAI,uBAAsB;AAAA,MAC/B,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MAClD;AAAA,MACA,kBAAkB,CAAC;AAAA,IACrB,CAAC;AAAA,EACH;AACF;;;AC7BO,SAAS,aAAgB;AAAA,EAC9B;AAAA,EACA;AAAA,EACA,gBAAgB;AAClB,GAIY;AACV,MAAI,iBAAiB,aAAa,OAAW,QAAO;AAEpD,SAAO,UAAU;AACnB;;;ACEO,SAAS,UAA8B,IAAa,cAAkC;AAC3F,MAAI;AACF,WAAO,GAAG;AAAA,EACZ,SAAS,OAAO;AACd,UAAM,aAAa,KAAK;AAAA,EAC1B;AACF;AA0CA,eAAsB,eACpB,IACA,cACY;AACZ,MAAI;AACF,WAAO,MAAM,GAAG;AAAA,EAClB,SAAS,OAAO;AACd,UAAM,aAAa,KAAK;AAAA,EAC1B;AACF;AAmCO,SAAS,gBACd,IACA,cACA,kBACG;AACH,MAAI;AACF,WAAO,GAAG;AAAA,EACZ,SAAS,OAAO;AACd,QAAI,iBAAiB,KAAK,CAAC,SAAS,iBAAiB,IAAI,GAAG;AAC1D,YAAM;AAAA,IACR;AACA,UAAM,aAAa,KAAK;AAAA,EAC1B;AACF;AAuCA,eAAsB,qBACpB,IACA,cACA,kBACY;AACZ,MAAI;AACF,WAAO,MAAM,GAAG;AAAA,EAClB,SAAS,OAAO;AACd,QAAI,iBAAiB,KAAK,CAAC,SAAS,iBAAiB,IAAI,GAAG;AAC1D,YAAM;AAAA,IACR;AACA,UAAM,aAAa,KAAK;AAAA,EAC1B;AACF;","names":[]}

package/dist/backend/core/global.d.cts

@@ -0,0 +1,294 @@
+export { B as BaseDto, a as BoundValidator, O as ObjectValidatorPort, S as SKIP_DTO_VALIDATION, V as ValidateObject } from '../../base-dto.class-D7W9iqoU.cjs';
+import { C as CodedError, V as ValidationError, G as GlobalErrorCode } from '../../validation-error.type-kD4_qNZ9.cjs';
+export { A as AppErrorCode, D as DomainErrorCode, a as ErrorCode, E as ErrorCodes, I as InfraErrorCode, P as PresentationErrorCode } from '../../validation-error.type-kD4_qNZ9.cjs';
+
+/**
+ * Error thrown when object validation fails.
+ *
+ * Contains structured validation errors with field paths and messages,
+ * making it easy to report specific validation failures to clients.
+ * Thrown by all validator implementations (Zod, ArkType, TypeBox, Valibot).
+ *
+ * **Flow:**
+ * 1. Validator throws `ObjectValidationError` with field-level errors
+ * 2. Controller catches and converts to {@link InvalidRequestError}
+ * 3. HTTP layer maps to 400 Bad Request with error details
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const dto = CreateUserDto.create(invalidData);
+ * } catch (error) {
+ *   if (error instanceof ObjectValidationError) {
+ *     console.log(error.validationErrors);
+ *     // [
+ *     //   { field: 'email', message: 'Invalid email format' },
+ *     //   { field: 'age', message: 'Must be a positive number' }
+ *     // ]
+ *   }
+ * }
+ * ```
+ */
+declare 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: ValidationError[];
+    /**
+     * 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, cause, validationErrors, }: {
+        message: string;
+        code?: GlobalErrorCode | string;
+        cause?: unknown;
+        validationErrors: ValidationError[];
+    });
+    /**
+     * 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: unknown): ObjectValidationError;
+}
+
+/**
+ * Checks if a field has changed by comparing the current value with a new value.
+ *
+ * Useful for detecting changes in update operations, supporting both partial
+ * and full update semantics.
+ *
+ * **Modes:**
+ * - **Partial update** (default): `undefined` means "keep existing value" (no change)
+ * - **Full update**: `undefined` means "set to undefined" (is a change if value !== undefined)
+ *
+ * **Limitation:** Uses strict equality (`!==`) for comparison, which only works
+ * correctly for primitives and reference equality. For objects or arrays, this
+ * compares references, not content. Two objects with identical content but
+ * different references will be considered "changed".
+ *
+ * For complex objects, either:
+ * - Compare by a unique identifier (e.g., `value.id !== newValue?.id`)
+ * - Use value objects with `.equals()` methods
+ * - Implement deep equality checking in your update logic
+ *
+ * @typeParam T - The type of the field being compared
+ * @param options - Comparison options
+ * @param options.value - The current field value
+ * @param options.newValue - The incoming value (may be undefined)
+ * @param options.partialUpdate - Whether to use partial update semantics (default: true)
+ * @returns `true` if the field has changed, `false` otherwise
+ *
+ * @example Partial update (PATCH semantics)
+ * ```typescript
+ * // undefined means "don't change"
+ * fieldChanged({ value: 'John', newValue: undefined }); // false
+ * fieldChanged({ value: 'John', newValue: 'Jane' });    // true
+ * fieldChanged({ value: 'John', newValue: 'John' });    // false
+ * ```
+ *
+ * @example Full update (PUT semantics)
+ * ```typescript
+ * // undefined means "set to undefined"
+ * fieldChanged({ value: 'John', newValue: undefined, partialUpdate: false }); // true
+ * ```
+ *
+ * @example Object comparison (reference-based)
+ * ```typescript
+ * const obj1 = { name: 'John' };
+ * const obj2 = { name: 'John' };
+ * fieldChanged({ value: obj1, newValue: obj2 });   // true (different references)
+ * fieldChanged({ value: obj1, newValue: obj1 });   // false (same reference)
+ * ```
+ */
+declare function fieldChanged<T>({ value, newValue, partialUpdate, }: {
+    value: T;
+    newValue: T | undefined;
+    partialUpdate?: boolean;
+}): boolean;
+
+/**
+ * Error wrapping utilities for boundary error handling.
+ *
+ * Provides functions to wrap code execution with error transformation,
+ * converting caught errors into typed Error instances.
+ * Useful at layer boundaries (infra, use case, controller) to normalize errors.
+ *
+ * @example Wrapping async database calls
+ * ```typescript
+ * const user = await wrapErrorAsync(
+ *   () => this.db.query('SELECT * FROM users WHERE id = ?', [id]),
+ *   (cause) => new DbError({ message: 'Failed to fetch user', cause }),
+ * );
+ * ```
+ *
+ * @example Wrapping sync operations
+ * ```typescript
+ * const parsed = wrapError(
+ *   () => JSON.parse(data),
+ *   (cause) => new InvariantViolationError({
+ *     message: 'Invalid JSON format',
+ *     cause,
+ *   }),
+ * );
+ * ```
+ *
+ * @module
+ */
+/**
+ * Factory function that creates an Error from a caught error.
+ *
+ * @typeParam E - The specific Error subclass to create
+ * @param cause - The original caught error
+ * @returns A new Error instance
+ */
+type ErrorFactory<E extends Error> = (cause: unknown) => E;
+/**
+ * Wraps a synchronous function with error transformation.
+ *
+ * Executes the provided function and catches any thrown errors,
+ * transforming them using the error factory.
+ *
+ * @typeParam T - The return type of the wrapped function
+ * @typeParam E - The Error subclass to throw on error
+ * @param fn - The function to execute
+ * @param errorFactory - Factory to create the typed error from the caught error
+ * @returns The result of the function if successful
+ * @throws {E} The transformed error if the function throws
+ *
+ * @example
+ * ```typescript
+ * const config = wrapError(
+ *   () => JSON.parse(configString),
+ *   (cause) => new InvariantViolationError({
+ *     message: 'Invalid configuration format',
+ *     code: 'CONFIG_PARSE_ERROR',
+ *     cause,
+ *   }),
+ * );
+ * ```
+ */
+declare function wrapError<T, E extends Error>(fn: () => T, errorFactory: ErrorFactory<E>): T;
+/**
+ * Wraps an asynchronous function with error transformation.
+ *
+ * Executes the provided async function and catches any thrown errors,
+ * transforming them using the error factory.
+ *
+ * @typeParam T - The return type of the wrapped function
+ * @typeParam E - The Error subclass to throw on error
+ * @param fn - The async function to execute
+ * @param errorFactory - Factory to create the typed error from the caught error
+ * @returns A promise resolving to the result if successful
+ * @throws {E} The transformed error if the function throws
+ *
+ * @example Repository usage
+ * ```typescript
+ * async findById(id: string): Promise<User | null> {
+ *   return wrapErrorAsync(
+ *     () => this.db.users.findUnique({ where: { id } }),
+ *     (cause) => new DbError({
+ *       message: `Failed to find user by ID: ${id}`,
+ *       cause,
+ *     }),
+ *   );
+ * }
+ * ```
+ *
+ * @example External service usage
+ * ```typescript
+ * async sendEmail(to: string, body: string): Promise<void> {
+ *   await wrapErrorAsync(
+ *     () => this.emailClient.send({ to, body }),
+ *     (cause) => new ExternalServiceError({
+ *       message: 'Email delivery failed',
+ *       code: 'EMAIL_SEND_FAILED',
+ *       cause,
+ *     }),
+ *   );
+ * }
+ * ```
+ */
+declare function wrapErrorAsync<T, E extends Error>(fn: () => Promise<T>, errorFactory: ErrorFactory<E>): Promise<T>;
+/**
+ * Constructor type for error classes (including abstract classes).
+ *
+ * Used to specify error types that should pass through without transformation.
+ */
+type ErrorConstructor = abstract new (...args: any[]) => Error;
+/**
+ * Wraps a synchronous function with conditional error transformation.
+ *
+ * Executes the provided function and catches any thrown errors.
+ * Errors matching any of the passthrough types are re-thrown as-is.
+ * All other errors are transformed using the error factory.
+ *
+ * @typeParam T - The return type of the wrapped function
+ * @typeParam E - The Error subclass to throw for unknown errors
+ * @param fn - The function to execute
+ * @param errorFactory - Factory to create the typed error from unknown errors
+ * @param passthroughTypes - Array of error classes to re-throw without transformation
+ * @returns The result of the function if successful
+ * @throws The original error if it matches a passthrough type
+ * @throws {E} The transformed error for unknown error types
+ *
+ * @example Controller boundary
+ * ```typescript
+ * const result = wrapErrorUnless(
+ *   () => this.requestMapper(input),
+ *   (cause) => new ControllerError({ message: 'Mapping failed', cause }),
+ *   [CodedError],
+ * );
+ * ```
+ */
+declare function wrapErrorUnless<T, E extends Error>(fn: () => T, errorFactory: ErrorFactory<E>, passthroughTypes: ErrorConstructor[]): T;
+/**
+ * Wraps an asynchronous function with conditional error transformation.
+ *
+ * Executes the provided async function and catches any thrown errors.
+ * Errors matching any of the passthrough types are re-thrown as-is.
+ * All other errors are transformed using the error factory.
+ *
+ * @typeParam T - The return type of the wrapped function
+ * @typeParam E - The Error subclass to throw for unknown errors
+ * @param fn - The async function to execute
+ * @param errorFactory - Factory to create the typed error from unknown errors
+ * @param passthroughTypes - Array of error classes to re-throw without transformation
+ * @returns A promise resolving to the result if successful
+ * @throws The original error if it matches a passthrough type
+ * @throws {E} The transformed error for unknown error types
+ *
+ * @example Use case boundary
+ * ```typescript
+ * return wrapErrorUnlessAsync(
+ *   () => this.handle(input),
+ *   (cause) => new UseCaseError({ message: 'Unexpected error', cause }),
+ *   [ObjectValidationError, UseCaseError, DomainError, InfraError],
+ * );
+ * ```
+ *
+ * @example Controller boundary
+ * ```typescript
+ * return wrapErrorUnlessAsync(
+ *   async () => {
+ *     const result = await this.useCase.execute(input);
+ *     return this.responseMapper(result);
+ *   },
+ *   (cause) => new ControllerError({ message: 'Controller failed', cause }),
+ *   [CodedError],
+ * );
+ * ```
+ */
+declare function wrapErrorUnlessAsync<T, E extends Error>(fn: () => Promise<T>, errorFactory: ErrorFactory<E>, passthroughTypes: ErrorConstructor[]): Promise<T>;
+
+export { CodedError, type ErrorConstructor, type ErrorFactory, GlobalErrorCode, ObjectValidationError, ValidationError, fieldChanged, wrapError, wrapErrorAsync, wrapErrorUnless, wrapErrorUnlessAsync };