@cosmneo/onion-lasagna 0.1.0

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

@@ -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.js';
+import { C as CodedError, V as ValidationError, G as GlobalErrorCode } from '../../validation-error.type-kD4_qNZ9.js';
+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.js';
+
+/**
+ * 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 };

package/dist/backend/core/global.js

@@ -0,0 +1,39 @@
+import {
+  wrapError,
+  wrapErrorAsync,
+  wrapErrorUnless,
+  wrapErrorUnlessAsync
+} from "../../chunk-OKFXZHBC.js";
+import {
+  BaseDto,
+  SKIP_DTO_VALIDATION
+} from "../../chunk-BKZOLGQW.js";
+import {
+  CodedError,
+  ErrorCodes,
+  ObjectValidationError
+} from "../../chunk-MQD5GXMT.js";
+import "../../chunk-CGZBV6BD.js";
+
+// 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;
+}
+export {
+  BaseDto,
+  CodedError,
+  ErrorCodes,
+  ObjectValidationError,
+  SKIP_DTO_VALIDATION,
+  fieldChanged,
+  wrapError,
+  wrapErrorAsync,
+  wrapErrorUnless,
+  wrapErrorUnlessAsync
+};
+//# sourceMappingURL=global.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/backend/core/global/utils/field-changed.util.ts"],"sourcesContent":["/**\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"],"mappings":";;;;;;;;;;;;;;;;;;AAiDO,SAAS,aAAgB;AAAA,EAC9B;AAAA,EACA;AAAA,EACA,gBAAgB;AAClB,GAIY;AACV,MAAI,iBAAiB,aAAa,OAAW,QAAO;AAEpD,SAAO,UAAU;AACnB;","names":[]}