@vytches/ddd-domain-services

@vytches/ddd-domain-services

Base classes and decorators for Domain Services

Domain Services encapsulate business operations that don't belong naturally on a single aggregate or value object.

Installation

pnpm add @vytches/ddd-domain-services

What's included

Base classes

Export	Kind	Description
PlainDomainService	class	Minimal base — no logger, no DI, no event bus. For pure stateless operations.
IBaseDomainService	class	Base with a built-in Logger via Logger.forContext()
AsyncDomainService	class	IBaseDomainService with async lifecycle hooks
EventAwareDomainService	class	IBaseDomainService + setEventBus(bus) for domain event publishing
UnitOfWorkAwareDomainService	class	IBaseDomainService + setUnitOfWork(uow) for transactional coordination

Decorator

Export	Kind	Description
DomainService	decorator	Marks a class for DI auto-discovery; stores service metadata
getDomainServiceMetadata(cls)	function	Reads metadata set by @DomainService
getDIDomainServiceMetadata(cls)	function	Reads DI-specific metadata
isDomainServicePendingDIRegistration(cls)	function	Returns true if the class has been decorated but not yet registered

Interfaces

Export	Kind	Description
IDomainService	interface	Core service contract (has serviceId)
IAsyncDomainService	interface	Adds initialize() / dispose()
IEventBusAware	interface	setEventBus(bus) contract
IUnitOfWorkAware	interface	setUnitOfWork(uow) contract
DomainServiceOptions	interface	Options accepted by @DomainService
DIServiceMetadata	interface	DI metadata shape
EnhancedDomainServiceOptions	interface	Extended options with DI lifetime and context

Errors

Export	Kind	Description
ServiceCircularError	class	Circular service dependency detected
ServiceDuplicateError	class	Service registered more than once
ServiceNotFoundError	class	Requested service not in registry

Usage

PlainDomainService — infrastructure-free

import { PlainDomainService } from '@vytches/ddd-domain-services';

class TaxCalculator extends PlainDomainService {
  constructor() {
    super('TaxCalculator');
  }

  calculate(amount: number, rate: number): number {
    return amount * rate;
  }
}

IBaseDomainService — with logging

import { IBaseDomainService } from '@vytches/ddd-domain-services';

class PricingService extends IBaseDomainService {
  constructor() {
    super('PricingService');
  }

  applyDiscount(price: number, pct: number): number {
    this.logger.debug('Applying discount', { price, pct });
    return price * (1 - pct / 100);
  }
}

EventAwareDomainService — publish domain events

import {
  EventAwareDomainService,
  DomainService,
} from '@vytches/ddd-domain-services';
import { DomainEvent } from '@vytches/ddd-events';

@DomainService('OrderFulfillmentService', { context: 'Orders' })
class OrderFulfillmentService extends EventAwareDomainService {
  constructor() {
    super('OrderFulfillmentService');
  }

  async fulfill(orderId: string): Promise<void> {
    // ... business logic ...
    await this.eventBus?.publish(
      new DomainEvent('OrderFulfilled', { orderId })
    );
  }
}

UnitOfWorkAwareDomainService — transactional coordination

import { UnitOfWorkAwareDomainService } from '@vytches/ddd-domain-services';

class TransferService extends UnitOfWorkAwareDomainService {
  constructor() { super('TransferService'); }

  async transfer(fromId: string, toId: string, amount: number): Promise<void> {
    await this.unitOfWork?.begin();
    try {
      // ... operations ...
      await this.unitOfWork?.commit();
    } catch {
      await this.unitOfWork?.rollback();
      throw;
    }
  }
}

Package boundaries

@vytches/ddd-domain-services depends on:

• @vytches/ddd-contracts — IEventBus
• @vytches/ddd-logging — Logger
• @vytches/ddd-repositories — IUnitOfWork

License

MIT