Overview

Entity Evolution: Building a Robust Host Entity

This section demonstrates the step-by-step evolution of a Host entity from basic TypeScript patterns to a robust, type-safe implementation using functional programming principles.

Foundation - Interface and Basic Class

BaseEntity provides id, createdAt, updatedAt and serialization helpers. This step defines IHost interface and Host class to describe the host entity structure.

Adding core Properties with refined types

Refined types ensure userId is a valid UUID and address is a structured value object. This step adds userId, dob, phoneNumber, address, socialLinks, and profileImage to the Host class.

Making Properties Optional with Option<T>

Option<T> makes missing values explicit and type-safe. This step wraps dob, phoneNumber, and profileImage in Option to handle optional host data.

Empty Constructor Setup

Constructors accept raw input and initialize BaseEntity fields via super(). This step adds an empty constructor that will be progressively filled with validation and assignment logic.

Adding Computed Properties

hasCompleteProfile checks if required profile fields are present for business rules. This step returns true when dob, phoneNumber, and profileImage all contain values.

Creating SerializedHost Type

SerializedHost represents the entity format for external systems and databases. This step defines a type with string id, nullable dates, and simplified value objects. Learn more: Type Boundaries

Introducing Maybe<T> Utility Type

Maybe<T> accepts T | Option<T> | null | undefined from different data sources. This step replaces verbose unions with a single Maybe<T> type alias.

Adding normalizeMaybe Utility

normalizeMaybe converts Maybe<T> to Option<T> at entity boundaries to keep domain logic uniform. This step handles null, undefined, existing Option, and raw values in one function.

Implementing Serialize Method

serialize converts internal Option<T> values back to external Maybe<T> format. This step uses optionToMaybe to transform Host fields for APIs and databases.

Adding optionToMaybe Utility

optionToMaybe centralizes the Option<T> to Maybe<T> transformation logic. This step extracts the helper to reduce duplication across serialize methods.

Adding Basic Guards to Class

Guards ensure field values meet business rules before entity creation. This step adds validatePhoneNumber and validateDateOfBirth as private static methods.

Using Guards in Constructor

Constructor validation prevents invalid entities from being created. This step normalizes inputs then runs validatePhoneNumber and validateDateOfBirth before assignment.

Making Constructor Private with Factory Method

Private constructors prevent unvalidated entity creation via new. This step adds Host.create factory method that always runs validation before instantiation.

Moving Guards to Separate File

Separate guard files enable reuse across domain and application layers. This step moves validatePhoneNumber and validateDateOfBirth into HostGuards class.

Extracting Utility Types to Separate File

Shared utilities prevent duplication across multiple entities. This step moves Maybe<T>, normalizeMaybe, and optionToMaybe into domain/utils/utils.ts.

Fixing the Messy Guards in Class

Factory methods compose normalizeMaybe with HostGuards validators and throw HostValidationError. This step replaces inline validation with external guard calls.

The Problem with Manual Encoding/Decoding

Manual serialization creates repetitive code, type gaps, and exception-based errors. This step lists the issues we will solve with Effect Schema.

Say Goodbye to Manual Serialization - Introducing Effect Schema

Effect Schema derives types and validation from a single definition. This step shows PersonSchema example that automatically generates types, validation, and transformations.

Creating Host Schema

HostSchema replaces manual types and validation with declarative field definitions. This step defines schema with StringToUUID, Optional fields, and composed value object schemas.

Deriving Types from Schema

Schema.Type and Schema.Encoded automatically generate runtime and serialized types. This step eliminates manual HostType and SerializedHost definitions by deriving them from HostSchema.

Integrating Guards into Schema

Schema.pipe integrates validation directly into field definitions. This step adds HostGuards.ValidDateOfBirth, ValidPhoneNumber, and ValidProfileImagePath to schema fields.

Simplified Entity with Effect Schema

Schema-derived types eliminate manual Option conversions in constructors. This step assigns HostType fields directly without normalizeMaybe or type casting.

Effect-Based Factory Method

Effect<Host, HostError, never> returns typed errors instead of throwing exceptions. This step composes S.decodeUnknown, guards, and value object creation in a single pipeline.

Simplified Serialization

S.encode(HostSchema) serializes entities without manual field mapping. This step replaces the multi-line serialize method with a single Effect-returning call.

import { BaseEntity, IEntity } from "@domain/utils/base.entity";
import { UUID } from "@domain/utils/refined.types";
import { Address } from "./address.vo";
import { SocialLinks } from "./socialLinks.vo";

interface IHost extends IEntity {
  userId: UUID;
  dob: Date;
  phoneNumber: number;
  profileImage: string;
}

export class Host extends BaseEntity implements IHost {
  // Properties will be added in the next step
}