@cosmneo/onion-lasagna 0.1.0

package/dist/base-dto.class-D7W9iqoU.d.cts

@@ -0,0 +1,146 @@
+/**
+ * Function signature for validating an object against a schema.
+ *
+ * @typeParam TSchema - The schema type (e.g., z.ZodType, Type from ArkType)
+ */
+type ValidateObject<TSchema> = <T>(schema: TSchema, value: unknown) => T;
+/**
+ * A validator bound to a specific schema.
+ *
+ * Created by {@link ObjectValidatorPort.withSchema} and used by
+ * {@link BaseDto} and {@link BaseValueObject} for validation.
+ *
+ * @typeParam T - The validated output type
+ *
+ * @example
+ * ```typescript
+ * const validator: BoundValidator<User> = createZodValidator(userSchema);
+ * const user = validator.validate(unknownInput); // Returns User or throws
+ * ```
+ */
+interface BoundValidator<T> {
+    /**
+     * Validates unknown input against the bound schema.
+     *
+     * @param value - The unknown value to validate
+     * @returns The validated and typed value
+     * @throws {ObjectValidationError} When validation fails
+     */
+    validate: (value: unknown) => T;
+}
+/**
+ * Port interface for object validation (Strategy pattern).
+ *
+ * This abstraction allows swapping between validation libraries
+ * (Zod, ArkType, TypeBox, Valibot) without changing application code.
+ *
+ * Implementations:
+ * - `ZodObjectValidator` - Zod schema validation
+ * - `ArkTypeObjectValidator` - ArkType validation
+ * - `TypeBoxObjectValidator` - TypeBox validation
+ * - `ValibotObjectValidator` - Valibot validation
+ *
+ * @typeParam TSchema - The schema type for the validation library
+ *
+ * @example
+ * ```typescript
+ * // Using Zod
+ * import { createZodValidator } from '@cosmneo/onion-lasagna/backend/core/validators/zod';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const validator = createZodValidator(schema);
+ * const data = validator.validate({ name: 'John', age: 30 });
+ *
+ * // Using ArkType
+ * import { createArkTypeValidator } from '@cosmneo/onion-lasagna/backend/core/validators/arktype';
+ * import { type } from 'arktype';
+ *
+ * const schema = type({ name: 'string', age: 'number' });
+ * const validator = createArkTypeValidator(schema);
+ * ```
+ */
+interface ObjectValidatorPort<TSchema> {
+    /**
+     * Validates a value directly against a schema.
+     *
+     * @param schema - The validation schema
+     * @param value - The unknown value to validate
+     * @returns The validated and typed value
+     * @throws {ObjectValidationError} When validation fails
+     */
+    validateObject: ValidateObject<TSchema>;
+    /**
+     * Creates a reusable validator bound to a specific schema.
+     *
+     * Use this to create validators for DTOs and Value Objects.
+     *
+     * @param schema - The validation schema to bind
+     * @returns A BoundValidator that can validate values against the schema
+     */
+    withSchema: <T>(schema: TSchema) => BoundValidator<T>;
+}
+
+/**
+ * Sentinel value to skip validation in DTO constructors.
+ *
+ * Use this when creating a DTO from already-validated data,
+ * such as when mapping between layers or in tests.
+ *
+ * @example
+ * ```typescript
+ * // Skip validation for already-validated data
+ * const dto = new CreateUserInputDto(validatedData, SKIP_DTO_VALIDATION);
+ * ```
+ */
+declare const SKIP_DTO_VALIDATION: "skip dto validation";
+/**
+ * Base class for Data Transfer Objects (DTOs).
+ *
+ * DTOs are validated data containers used to transfer data between layers.
+ * Unlike Value Objects, DTOs are not domain concepts - they are purely
+ * for data transfer and validation at system boundaries.
+ *
+ * Key differences from Value Objects:
+ * - **DTOs**: Transfer data between layers (e.g., request/response payloads)
+ * - **Value Objects**: Represent domain concepts with behavior (e.g., Email, Money)
+ *
+ * @typeParam T - The shape of the data being transferred
+ *
+ * @example
+ * ```typescript
+ * // Define a DTO with validation
+ * class CreateUserInputDto extends BaseDto<{ name: string; email: string }> {
+ *   private constructor(data: unknown, validator: BoundValidator<{ name: string; email: string }>) {
+ *     super(data, validator);
+ *   }
+ *
+ *   static create(data: unknown): CreateUserInputDto {
+ *     return new CreateUserInputDto(data, createUserValidator);
+ *   }
+ * }
+ *
+ * // Usage in a controller
+ * const dto = CreateUserInputDto.create(request.body);
+ * console.log(dto.data.name); // Typed and validated
+ * ```
+ */
+declare class BaseDto<T> {
+    private readonly _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: T, validator: BoundValidator<T> | typeof SKIP_DTO_VALIDATION);
+    /**
+     * The validated data payload.
+     *
+     * @returns The validated data of type T
+     */
+    get data(): T;
+}
+
+export { BaseDto as B, type ObjectValidatorPort as O, SKIP_DTO_VALIDATION as S, type ValidateObject as V, type BoundValidator as a };

package/dist/base-dto.class-D7W9iqoU.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Function signature for validating an object against a schema.
+ *
+ * @typeParam TSchema - The schema type (e.g., z.ZodType, Type from ArkType)
+ */
+type ValidateObject<TSchema> = <T>(schema: TSchema, value: unknown) => T;
+/**
+ * A validator bound to a specific schema.
+ *
+ * Created by {@link ObjectValidatorPort.withSchema} and used by
+ * {@link BaseDto} and {@link BaseValueObject} for validation.
+ *
+ * @typeParam T - The validated output type
+ *
+ * @example
+ * ```typescript
+ * const validator: BoundValidator<User> = createZodValidator(userSchema);
+ * const user = validator.validate(unknownInput); // Returns User or throws
+ * ```
+ */
+interface BoundValidator<T> {
+    /**
+     * Validates unknown input against the bound schema.
+     *
+     * @param value - The unknown value to validate
+     * @returns The validated and typed value
+     * @throws {ObjectValidationError} When validation fails
+     */
+    validate: (value: unknown) => T;
+}
+/**
+ * Port interface for object validation (Strategy pattern).
+ *
+ * This abstraction allows swapping between validation libraries
+ * (Zod, ArkType, TypeBox, Valibot) without changing application code.
+ *
+ * Implementations:
+ * - `ZodObjectValidator` - Zod schema validation
+ * - `ArkTypeObjectValidator` - ArkType validation
+ * - `TypeBoxObjectValidator` - TypeBox validation
+ * - `ValibotObjectValidator` - Valibot validation
+ *
+ * @typeParam TSchema - The schema type for the validation library
+ *
+ * @example
+ * ```typescript
+ * // Using Zod
+ * import { createZodValidator } from '@cosmneo/onion-lasagna/backend/core/validators/zod';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const validator = createZodValidator(schema);
+ * const data = validator.validate({ name: 'John', age: 30 });
+ *
+ * // Using ArkType
+ * import { createArkTypeValidator } from '@cosmneo/onion-lasagna/backend/core/validators/arktype';
+ * import { type } from 'arktype';
+ *
+ * const schema = type({ name: 'string', age: 'number' });
+ * const validator = createArkTypeValidator(schema);
+ * ```
+ */
+interface ObjectValidatorPort<TSchema> {
+    /**
+     * Validates a value directly against a schema.
+     *
+     * @param schema - The validation schema
+     * @param value - The unknown value to validate
+     * @returns The validated and typed value
+     * @throws {ObjectValidationError} When validation fails
+     */
+    validateObject: ValidateObject<TSchema>;
+    /**
+     * Creates a reusable validator bound to a specific schema.
+     *
+     * Use this to create validators for DTOs and Value Objects.
+     *
+     * @param schema - The validation schema to bind
+     * @returns A BoundValidator that can validate values against the schema
+     */
+    withSchema: <T>(schema: TSchema) => BoundValidator<T>;
+}
+
+/**
+ * Sentinel value to skip validation in DTO constructors.
+ *
+ * Use this when creating a DTO from already-validated data,
+ * such as when mapping between layers or in tests.
+ *
+ * @example
+ * ```typescript
+ * // Skip validation for already-validated data
+ * const dto = new CreateUserInputDto(validatedData, SKIP_DTO_VALIDATION);
+ * ```
+ */
+declare const SKIP_DTO_VALIDATION: "skip dto validation";
+/**
+ * Base class for Data Transfer Objects (DTOs).
+ *
+ * DTOs are validated data containers used to transfer data between layers.
+ * Unlike Value Objects, DTOs are not domain concepts - they are purely
+ * for data transfer and validation at system boundaries.
+ *
+ * Key differences from Value Objects:
+ * - **DTOs**: Transfer data between layers (e.g., request/response payloads)
+ * - **Value Objects**: Represent domain concepts with behavior (e.g., Email, Money)
+ *
+ * @typeParam T - The shape of the data being transferred
+ *
+ * @example
+ * ```typescript
+ * // Define a DTO with validation
+ * class CreateUserInputDto extends BaseDto<{ name: string; email: string }> {
+ *   private constructor(data: unknown, validator: BoundValidator<{ name: string; email: string }>) {
+ *     super(data, validator);
+ *   }
+ *
+ *   static create(data: unknown): CreateUserInputDto {
+ *     return new CreateUserInputDto(data, createUserValidator);
+ *   }
+ * }
+ *
+ * // Usage in a controller
+ * const dto = CreateUserInputDto.create(request.body);
+ * console.log(dto.data.name); // Typed and validated
+ * ```
+ */
+declare class BaseDto<T> {
+    private readonly _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: T, validator: BoundValidator<T> | typeof SKIP_DTO_VALIDATION);
+    /**
+     * The validated data payload.
+     *
+     * @returns The validated data of type T
+     */
+    get data(): T;
+}
+
+export { BaseDto as B, type ObjectValidatorPort as O, SKIP_DTO_VALIDATION as S, type ValidateObject as V, type BoundValidator as a };