Meaningful Domain Models in TypeScript

Context

TypeScript 프로젝트에서 문법적으로 정상이지만 비즈니스 규칙을 위반하는 상태(결제된 주문인데 인보이스 ID 없음, 마지막 항목을 제거한 주문 등)가 프로덕션에서 발생하고 있다. 검증 로직이 특정 경로(use case, controller)에만 존재하면 다른 경로에서 상태 변경 시 검증을 우회할 수 있다.

Technical Solution

• 불변성(Invariant)을 엔티티 클래스에 등록: 상태 읽기(readState()) 호출 시마다 항상 검증되므로 어떤 경로에서든 규칙 위반 감지
• Result 패턴으로 실패를 명시화: 함수 반환 타입에 성공값과 실패값을 모두 명시(Result<Success, Failure>)하여 호출자가 반드시 두 경우 처리
• 도메인 이벤트로 상태 변경 기록: 모든 연산이 불변 이벤트 객체를 반환하고 엔티티 상태와 함께 원자적으로 저장
• 타입화된 도메인 에러: 단순 메시지 문자열 대신 구조화된 컨텍스트(available, amount 등)를 포함한 에러 객체로 로깅 품질 향상
• Ontologic 라이브러리 활용: DomainEntity, BaseDomainInvariant, DomainEvent, Result 등 패턴 구현 제공

Key Takeaway

비즈니스 규칙을 검증 코드로 흩어놓지 말고 엔티티의 불변성으로 선언하면, 개발자가 실수로 규칙을 우회할 기회 자체가 없어진다. 함수 시그니처에 실패 케이스를 명시하고 이벤트로 모든 변경을 기록하면 도메인 로직의 안정성과 추적성이 동시에 확보된다.