DEV Community: Rathish Shriyan

Enhancing Domain-Driven Design with Functional Error Handling in TypeScript

Rathish Shriyan — Mon, 28 Oct 2024 20:32:02 +0000

Adding Functional Flavor to Domain-Driven Design with Either

Incorporating functional programming concepts into domain-driven design (DDD) can add clarity and expressiveness to our code. When implementing business logic methods, we often face multiple potential outcomes. Handling these outcomes in a readable, maintainable way becomes crucial as business requirements evolve. This is where the Either<T> class shines, giving us an elegant solution to capture success and error states in a way that aligns with functional programming principles.

User Story Example: Creating a Profile

Let’s consider the following user story:

User Story:

As a user, I need to be able to create my profile in the application. I will provide certain information from a recent billing statement, and the system should identify me and set up my profile accordingly. Wholesale and cash customers are not allowed to register, nor are users without permission to add an account.

This requires validating user information, which could lead to a variety of outcomes:

UserNotFound
AccountIsAlreadyAssociated
AccountIsWholeSaleError
CashCustomerError
NoPermissionToAddAccountError

Previous Approach: Using Standard Error Types

In previous implementations, I used a standard error type in the method signature:

public AddAccountBusinessFlow(data): Promise<bool | Error>

This approach returned either a boolean on success or an error on failure. Calling code could then check against various errors:

if (error == UserNotFound) return response.status(404);
else if (error == AccountIsAlreadyAssociated || error == AccountIsWholeSaleError) return response.status(400);

While functional, this quickly becomes unwieldy as conditions grow. A more readable and expressive method signature would improve maintainability, self-documenting the method's possible outcomes.

Functional Solution: The Either Type

Inspired by Rust’s Result monad and Either type, I explored using TypeScript’s Either to handle these multiple outcomes in a more expressive manner. By using an Either type, we can clarify the semantics of our method signatures and improve readability in a domain-driven context.

Here's how an Either implementation can make the method more expressive:

Either<
    | UserNotFound
    | AccountIsAlreadyAssociated
    | CashCustomerError
    | NoPermissionToAddAccountError,
      AddAccountSuccess>

With this Either type, all possible error conditions are listed on the left, and the success state (AddAccountSuccess) is on the right. This pattern makes it clear that the function can either succeed with a valid outcome or return one of the specific error states. The method signature itself now serves as documentation, making it easier for anyone reading the code to understand potential outcomes.

Either Implementation in TypeScript

Here’s the Either implementation I used, inspired by an excellent article on expressive error handling in TypeScript here:

export type Either<L, A> = Left<L, A> | Right<L, A>;

export class Left<L, A> {
  readonly value: L;

  constructor(value: L) {
    this.value = value;
  }

  isLeft(): this is Left<L, A> {
    return true;
  }

  isRight(): this is Right<L, A> {
    return false;
  }
}

export class Right<L, A> {
  readonly value: A;

  constructor(value: A) {
    this.value = value;
  }

  isLeft(): this is Left<L, A> {
    return false;
  }

  isRight(): this is Right<L, A> {
    return true;
  }
}

export const left = <L, A>(l: L): Either<L, A> => {
  return new Left(l);
};

export const right = <L, A>(a: A): Either<L, A> => {
  return new Right(l);
};

This Either type allows us to encapsulate both success and error states, enforcing at compile time that the caller must handle both cases.

Using `Either` in `AddAccountBusinessFlow`

With the Either pattern, our AddAccountBusinessFlow can now return specific outcomes in a functional style, improving clarity and reliability. Here’s how we can use it:

public AddAccountBusinessFlow(data): Promise<Either<
  | UserNotFound
  | AccountIsAlreadyAssociated
  | CashCustomerError
  | NoPermissionToAddAccountError,
    AddAccountSuccess>> {

  // Business logic here...

  if (!userExists) return left(new UserNotFound());
  if (accountIsWholesale) return left(new AccountIsWholeSaleError());
  if (!userHasPermission) return left(new NoPermissionToAddAccountError());

  return right(new AddAccountSuccess());
}

Benefits of the Either Approach in Domain-Driven Design

Semantic Clarity: By naming each error explicitly in the method signature, we create a more readable and self-documenting method. This is invaluable as the codebase grows.
Compile-Time Safety: Using Either enforces that both success and error states are considered, reducing the risk of unhandled errors and making refactoring safer.
Functional Flow: Either facilitates functional-style error handling, reducing branching code and making error handling more declarative.
Enhanced Testability: Testing individual outcomes is straightforward. The function’s output type captures all possible paths, making it easy to verify each scenario.

Conclusion

The Either type brings the benefits of functional programming to TypeScript, making complex business logic more manageable and expressive. By applying this to domain-driven design, we get a cleaner, more readable codebase that is easier to maintain and test.

Utilizing Adapter pattern for hiding external libraries

Rathish Shriyan — Wed, 25 Sep 2024 16:27:38 +0000

When working on a project, integrating external libraries is often necessary. However, tightly coupling these libraries with the code can make it difficult to swap them out or refactor without risking regressions. That’s why I started using the Adapter Pattern—it hides external dependencies, allowing seamless library replacement without breaking the rest of the application.

My application code dealt directly with momentjs and was tightly coupled to it. Since momentjs was deprecated, I wanted to switch to another library: dayjs. Switching to a new library meant, not only finding and updating the references but also retesting every functionality the refactor impacts. Instead of replacing momentjs constructs with dayjs everywhere, I decided to abstract it behind an adapter. This allowed me to keep the rest of my codebase library-agnostic while having the flexibility to swap in another library if necessary—without fear of introducing bugs or needing to retest every component.

Let’s break down the key parts of this implementation:

Private Constructor:
I made the constructor private to enforce the abstraction. This way, only the DateTimeAdapter class manages the dayjs instance internally, ensuring no external code relies on dayjs directly.
Returning New Instances:
Methods like add() return a new DateTimeAdapter instance. This ensures immutability, which is crucial when working with dates. Mutating the current instance would lead to unexpected behavior in the rest of the system.
Immutability
Returning New Instances: When operations like add, subtract, set, or clone are performed, you return a new instance of DateTimeAdapter instead of modifying the existing one. This practice ensures immutability, which is vital for entities like dates, where accidental mutations could lead to unexpected behavior across the application.

One of the key principles here is “writing against a contract.” In this case, the contract is the DateTimeAdapter class, which defines the interface my application code interacts with. The external library (dayjs, in this example) becomes a detail that can be swapped or replaced. This practice of coding to an interface, not an implementation, keeps the system flexible and easier to maintain.

// Abstract an external library for dealing with dates, datetime.
import dayjs, { OpUnitType, QUnitType, UnitType } from 'dayjs';

import timezone from 'dayjs/plugin/timezone';
import weekday from 'dayjs/plugin/weekday';
import utc from 'dayjs/plugin/utc';

import { isNil } from '@utils';
import { LocalDateTimeString, LocalTimeString } from '../utils/local_date_time';

dayjs.extend(utc);
dayjs.extend(timezone);
dayjs.extend(weekday);

export enum Timezone {
  UTC = 'UTC',
  PST = 'America/Los_Angeles',
  CST = 'America/Chicago',
  EST = 'America/New_York',
}
// Mimics the types accepted by Dayjs, but purposely removes Dayjs as one of the accepted types.
export type DateTimeAdapterTypes = string | number | Date | null | undefined;

export class DateTimeAdapter {
  // Holds the library core instance, this can be swapped with another library like moment
  private instance: dayjs.Dayjs;

  // Purposely made private for internal use, we cannot expose this outside since that
  // leaks the library specific type(dayjs.Dayjs) to the caller. This will break abstraction.
  private constructor(dayjs: dayjs.Dayjs) {
    this.instance = dayjs;
  }

  static create(value: DateTimeAdapterTypes = undefined): DateTimeAdapter {
    if (isNil(value)) {
      return new DateTimeAdapter(dayjs());
    }
    return new DateTimeAdapter(dayjs(value));
  }

  format(template?: string): string {
    return this.instance.format(template);
  }

  isBefore(value?: DateTimeAdapterTypes | DateTimeAdapter): boolean {
    if (value instanceof DateTimeAdapter) {
      return this.instance.isBefore(value.toDate());
    } else {
      return this.instance.isBefore(value);
    }
  }

  isAfter(value?: DateTimeAdapterTypes | DateTimeAdapter): boolean {
    if (value instanceof DateTimeAdapter) {
      return this.instance.isAfter(value.toDate());
    } else {
      return this.instance.isAfter(value);
    }
  }

  // https://day.js.org/docs/en/display/difference
  diff(value: DateTimeAdapterTypes | DateTimeAdapter, unit?: string): number {
    if (value instanceof DateTimeAdapter) {
      return this.instance.diff(value.toDate(), <QUnitType | OpUnitType>unit);
    } else {
      return this.instance.diff(value, <QUnitType | OpUnitType>unit);
    }
  }

  // Important to not mutate the current instance, modifications should always return new instance
  add(value: number, unit: string): DateTimeAdapter {
    // returns a clone i.e. a new dayJs, so the current instance should not be updated.
    return new DateTimeAdapter(this.instance.add(value, unit));
  }

  toDate(): Date {
    return this.instance.toDate();
  }

  valueOf(): number {
    return this.instance.valueOf();
  }

  isValid(): boolean {
    return this.instance.isValid();
  }

  subtract(number: number, unit: string): DateTimeAdapter {
    return new DateTimeAdapter(this.instance.subtract(number, unit));
  }

  set(hour: string, number: number): DateTimeAdapter {
    return DateTimeAdapter.create(
      this.instance.set(<UnitType>hour, number).toDate(),
    );
  }

  date(): number {
    return this.instance.date();
  }

  clone(): DateTimeAdapter {
    return new DateTimeAdapter(this.instance.clone());
  }

  isSame(value: DateTimeAdapter): boolean {
    return this.instance.isSame(value.toDate());
  }

  toLocalTimeString(): LocalTimeString {
    return this.instance.format('HH:mm');
  }

  setTimezone(zone: Timezone): DateTimeAdapter {
    return new DateTimeAdapter(this.instance.tz(zone));
  }

  weekday(): number {
    return this.instance.weekday();
  }

  hour(): number {
    return this.instance.hour();
  }
}

Github link

Looking back, implementing the Adapter Pattern has saved me a lot of headaches. It’s allowed me to keep my codebase flexible and protected from the quirks of external libraries. Whether it’s changing libraries or just needing to adapt to new project requirements, this pattern ensures I’m not locked into one solution. Going forward, I plan to apply this in other parts of my code where external dependencies exist—it’s a small investment that pays off big.