Packages

@xtaskjs/value-objects

Value object primitives, conversion helpers, DTO decorators, and DI factory integration helpers.

npm install @xtaskjs/value-objects reflect-metadata Package path: packages/value-objects

Overview

What this package owns in the runtime

Value objects gives xtaskjs projects a consistent way to model domain primitives and structured payload wrappers. It standardizes conversion from raw input, JSON strings, and serialized payloads while optionally bridging DTO transformation and DI-managed factory creation.

What it provides

Base classes cover string, number, boolean, bigint, date, and JSON-backed value objects.
Conversion helpers normalize raw values, JSON strings, and serialized payloads into predictable wrappers.
TransformValueObject() plugs value objects into class-transformer DTO pipelines.
createValueObjectFactory(), InjectableValueObjectFactory, and ValueObjectFactoryFor() support container-managed creation flows.

How it fits

Fits naturally with @xtaskjs/common ValidationPipe once DTOs are transformed through class-transformer.
Can register DI-friendly factories through @xtaskjs/core when value object creation belongs in services.
Useful in HTTP DTOs, domain models, and persistence boundaries where primitive normalization must stay explicit.

Usage Chart

How strongly this package shapes the runtime

Domain modeling

5/5

Serialization

5/5

DTO pipelines

4/5

Dependency Injection

4/5

Integrations

3/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Import reflect-metadata before defining value objects that rely on decorator-driven DTO or DI integrations.

During CreateApplication()

The package itself does not register a lifecycle manager, but ValueObjectFactoryFor() can register DI-ready factories through @xtaskjs/core during module loading.

During app.close()

Value objects are pure wrappers with no owned resources, so shutdown usually means letting container-managed factories disappear with the rest of the app.

API Surface

Representative exports from the upstream package

Types and contracts

JsonValue
ValueObjectLike
ValueObjectStaticFactory
ValueObjectFactory
TransformValueObjectOptions
ValueObjectFactoryProviderOptions

Conversion helpers

isValueObject
unwrapValue
parseJsonValue
looksLikeJsonString
toPlainValue
toSerializableValue
toJsonString

Base value objects

ValueObject
StringValueObject
NumberValueObject
BooleanValueObject
BigIntValueObject
DateValueObject
JsonValueObject

Factory helpers

createValueObjectFactory
InjectableValueObjectFactory
ValueObjectFactoryFor
fromPlainValue
fromJsonValue
fromAutoValue

DTO decorators

TransformValueObject

Usage

Typical adoption flow

1. Define value object classes

Extend StringValueObject, NumberValueObject, DateValueObject, or JsonValueObject and normalize invariants inside the constructor.

2. Transform DTO input

Use TransformValueObject() on DTO fields when request payloads should become domain-friendly wrappers during class-transformer conversion.

3. Add factories when needed

Create ad hoc factories with createValueObjectFactory() or register InjectableValueObjectFactory implementations when services should resolve them from the container.

Example

Reference snippet

DTO transformation plus DI factory registration

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" });

Samples

Official samples to inspect next

Reference samples: Package README examples and package tests currently provide the primary reference.