NestJS DDD Library

A comprehensive library providing Domain-Driven Design (DDD) building blocks for NestJS applications. This library helps you implement DDD patterns such as Value Objects, Entities, and Aggregates in your NestJS projects with TypeScript.

Features

• Entities: Objects that have a distinct identity that runs through time and different states
• Aggregates: Cluster of domain objects that can be treated as a single unit
• Result types: Using oxide.ts for type-safe error handling
• Value Objects: Immutable objects that contain attributes but have no conceptual identity with examples:
  • UUID: Built-in UUID v7 generation and validation
  • Email: Email value object with validation

Installation

# Using npm
npm install @libs-for-dev/nestjs-ddd-library

# Using yarn
yarn add @libs-for-dev/nestjs-ddd-library

# Using pnpm
pnpm add @libs-for-dev/nestjs-ddd-library

Peer Dependencies

This library requires the following peer dependencies:

yarn add @nestjs/cqrs class-validator fast-equals oxide.ts ui7

Usage Examples

Value Objects

UUID

import { Uuid } from '@libs-for-dev/nestjs-ddd-library';

// Generate a new UUID (v7)
const uuid = Uuid.generate();
console.log(uuid.value); // Generated UUID v7 string

// Create from existing UUID string
const uuidResult = Uuid.create('de49eb8d-9199-4046-a784-d015148f95a7');

if (uuidResult.isOk()) {
  const uuid = uuidResult.unwrap();
  console.log(uuid.value); // de49eb8d-9199-4046-a784-d015148f95a7
} else {
  // Handle error
  console.error(uuidResult.unwrapErr());
}

Email

import { Email } from '@libs-for-dev/nestjs-ddd-library';

// Create an Email value object
const emailResult = Email.create('[email protected]');

if (emailResult.isOk()) {
  const email = emailResult.unwrap();
  console.log(email.value); // [email protected]
} else {
  // Handle error
  console.error(emailResult.unwrapErr());
}

Entities

import { AbstractEntity, Uuid } from '@libs-for-dev/nestjs-ddd-library';

// Define entity properties
interface UserProps {
  email: string;
  name: string;
}

// Create an entity class
class User extends AbstractEntity<Uuid, UserProps> {
  public static create(id: Uuid, props: UserProps): User {
    return new User(id, props);
  }

  // Add domain methods here
  public updateName(name: string): void {
    this.propsData = {
      props: {
        ...this.props,
        name
      }
    };
  }
}

// Usage
const userId = Uuid.generate();
const user = User.create(userId, {
  email: '[email protected]',
  name: 'John Doe'
});

// Access properties
console.log(user.id.value); // UUID
console.log(user.props.name); // John Doe

// Update properties using domain methods
user.updateName('Jane Doe');
console.log(user.props.name); // Jane Doe

Domain Events

The library integrates with NestJS CQRS to support domain events:

import { AbstractEntity, Uuid } from '@libs-for-dev/nestjs-ddd-library';
import { IEvent } from '@nestjs/cqrs';

// Define a domain event
class UserCreatedEvent implements IEvent {
  constructor(public readonly userId: string, public readonly email: string) {}
}

// Entity with domain events
class User extends AbstractEntity<Uuid, UserProps> {
  public static create(id: Uuid, props: UserProps): User {
    const user = new User(id, props);
    user.apply(new UserCreatedEvent(id.value, props.email));
    return user;
  }
}

// In your NestJS application
@EventsHandler(UserCreatedEvent)
export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
  handle(event: UserCreatedEvent) {
    console.log(`User created: ${event.userId} with email ${event.email}`);
  }
}

License

MIT