Paquetes

@xtaskjs/value-objects

Primitivas de value objects, utilidades de conversión, decoradores para DTO y helpers de integración con fábricas DI.

npm install @xtaskjs/value-objects reflect-metadata Ruta del paquete: packages/value-objects

Resumen

Qué controla este paquete en el runtime

Value objects ofrece a los proyectos xtaskjs una forma coherente de modelar primitivas de dominio y envoltorios de payload estructurados. Estandariza la conversión desde entrada cruda, cadenas JSON y payloads serializados, y además puede enlazar la transformación de DTO con la creación de fábricas gestionadas por DI.

Qué ofrece

Las clases base cubren value objects respaldados por string, number, boolean, bigint, date y JSON.
Las utilidades de conversión normalizan valores crudos, cadenas JSON y payloads serializados en envoltorios predecibles.
TransformValueObject() integra los value objects en las canalizaciones DTO de class-transformer.
createValueObjectFactory(), InjectableValueObjectFactory y ValueObjectFactoryFor() permiten flujos de creación gestionados por el contenedor.

Cómo encaja

Encaja de forma natural con ValidationPipe de @xtaskjs/common una vez que los DTO se transforman mediante class-transformer.
Puede registrar fábricas compatibles con DI a través de @xtaskjs/core cuando la creación de value objects pertenece a servicios.
Resulta útil en DTO HTTP, modelos de dominio y límites de persistencia donde la normalización de primitivas debe seguir siendo explícita.

Mapa de uso

Qué peso tiene este paquete dentro del runtime

Modelado de dominio

5/5

Serialización

5/5

Canalizaciones DTO

4/5

Inyección de dependencias

4/5

Integraciones

3/5

Flujo del paquete

Cómo atraviesa este paquete las fases del runtime de xtaskjs

Antes del arranque

Importa reflect-metadata antes de definir value objects que dependan de integraciones DTO o DI basadas en decoradores.

Durante CreateApplication()

El paquete en sí no registra un gestor de ciclo de vida, pero ValueObjectFactoryFor() puede registrar fábricas preparadas para DI a través de @xtaskjs/core durante la carga del módulo.

Durante app.close()

Los value objects son envoltorios puros sin recursos propios, así que el apagado normalmente consiste en dejar que las fábricas gestionadas por el contenedor desaparezcan junto con el resto de la aplicación.

Superficie API

Exports representativos del paquete original

Tipos y contratos

JsonValue
ValueObjectLike
ValueObjectStaticFactory
ValueObjectFactory
TransformValueObjectOptions
ValueObjectFactoryProviderOptions

Utilidades de conversión

isValueObject
unwrapValue
parseJsonValue
looksLikeJsonString
toPlainValue
toSerializableValue
toJsonString

Value objects base

ValueObject
StringValueObject
NumberValueObject
BooleanValueObject
BigIntValueObject
DateValueObject
JsonValueObject

Utilidades de fábrica

createValueObjectFactory
InjectableValueObjectFactory
ValueObjectFactoryFor
fromPlainValue
fromJsonValue
fromAutoValue

Decoradores DTO

TransformValueObject

Uso

Flujo típico de adopción

1. Define clases de value objects

Extiende StringValueObject, NumberValueObject, DateValueObject o JsonValueObject y normaliza las invariantes dentro del constructor.

2. Transforma la entrada DTO

Usa TransformValueObject() en campos DTO cuando los payloads de petición deban convertirse en envoltorios cómodos para el dominio durante la conversión con class-transformer.

3. Añade fábricas cuando haga falta

Crea fábricas ad hoc con createValueObjectFactory() o registra implementaciones de InjectableValueObjectFactory cuando los servicios deban resolverlas desde el contenedor.

Ejemplo

Fragmento de referencia

Transformación de DTO más registro de fábrica DI

import { plainToInstance } from "class-transformer";
import {
  InjectableValueObjectFactory,
  StringValueObject,
  TransformValueObject,
  ValueObjectFactoryFor,
} from "@xtaskjs/value-objects";

class EmailAddress extends StringValueObject {
  constructor(value: string) {
    const normalized = value.trim().toLowerCase();
    if (!normalized.includes("@")) {
      throw new Error("Invalid email address");
    }
    super(normalized);
  }
}

class CreateUserDto {
  @TransformValueObject(EmailAddress)
  email!: EmailAddress;
}

@ValueObjectFactoryFor(EmailAddress)
class EmailAddressFactory extends InjectableValueObjectFactory<EmailAddress> {}

const dto = plainToInstance(CreateUserDto, { email: "USER@Example.com" });

Ejemplos

Ejemplos oficiales para revisar después

Ejemplos de referencia: Package README examples and package tests currently provide the primary reference.