@vytches/ddd-value-objects

@vytches/ddd-value-objects

Base value object class, EntityId, and branded ID types

Provides the foundation for value objects in DDD — immutability, structural equality, and type-safe entity identifiers.

Installation

pnpm add @vytches/ddd-value-objects

What's included

Export	Kind	Description
BaseValueObject<T>	class	Abstract base for value objects; deep-freezes internal value; implements equals() via structural comparison
ValueObjectValidator<T>	interface	validate(value: T): boolean — implement to add invariant checking
EntityId<T>	class	Enhanced entity identifier extending the contracts EntityId; adds UUID/integer/text validation, create(), fromString(), fromNumber()
EntityIdFactory	class	Deprecated — will be removed in v1.0.0; use EntityId.create() directly
BrandedId<Tag>	type	Compile-time branded EntityId<string> — prevents mixing IDs across aggregate types
createBrandedId<Tag>(id)	function	Casts an EntityId to BrandedId<Tag>
newBrandedId<Tag>()	function	Creates a new UUID-based BrandedId<Tag>
brandedIdFromUUID<Tag>(uuid)	function	Creates a BrandedId<Tag> from an existing UUID string
brandedIdFromText<Tag>(text)	function	Creates a BrandedId<Tag> from a text string
IEntityId<T>	interface	Re-exported from @vytches/ddd-contracts
IEntityIdFactory	interface	Re-exported from @vytches/ddd-contracts
IdType	type	Re-exported from @vytches/ddd-contracts — 'uuid' | 'integer' | 'text'

Note on bundled domain examples

This package does not export Email, Money, Address, PhoneNumber, DateRange, or other concrete domain value objects. Those are application-level types — implement them in your own domain layer using BaseValueObject as the base class.

Quick start

Custom value object

import { BaseValueObject } from '@vytches/ddd-value-objects';

interface MoneyProps {
  amount: number;
  currency: string;
}

class Money extends BaseValueObject<MoneyProps> {
  constructor(amount: number, currency: string) {
    super({ amount, currency });
  }

  validate(value: MoneyProps): boolean {
    return value.amount >= 0 && value.currency.length === 3;
  }

  get amount(): number {
    return this.value.amount;
  }
  get currency(): string {
    return this.value.currency;
  }

  add(other: Money): Money {
    if (this.currency !== other.currency) throw new Error('Currency mismatch');
    return new Money(this.amount + other.amount, this.currency);
  }
}

const price = new Money(10, 'USD');
const tax = new Money(1.5, 'USD');
const total = price.add(tax);

console.log(total.equals(new Money(11.5, 'USD'))); // true

EntityId

import { EntityId } from '@vytches/ddd-value-objects';

// Generate a new UUID-based ID
const id = EntityId.create(); // EntityId<string> with UUID

// From an existing UUID string
const fromString = EntityId.fromString('550e8400-e29b-41d4-a716-446655440000');

// From an integer
const fromNumber = EntityId.fromNumber(42);

console.log(id.getValue()); // '550e8400-...'
console.log(id.equals(EntityId.fromString(id.getValue()))); // true

Branded IDs

import {
  BrandedId,
  newBrandedId,
  brandedIdFromUUID,
} from '@vytches/ddd-value-objects';

type OrderId = BrandedId<'Order'>;
type CustomerId = BrandedId<'Customer'>;

const orderId: OrderId = newBrandedId<'Order'>();
const customerId: CustomerId = newBrandedId<'Customer'>();

function shipOrder(id: OrderId): void {
  /* ... */
}

shipOrder(orderId); // OK
shipOrder(customerId); // TypeScript compile error!

Package boundaries

@vytches/ddd-value-objects depends on:

• @vytches/ddd-contracts — EntityId base class, IEntityId, IdType
• @vytches/ddd-domain-primitives — error types
• @vytches/ddd-utils — LibUtils, Result

License

MIT