맞춤 정장 TypeScript

들어가며

안녕하세요. 노머스에서 백엔드 개발을 하고 있는 유영기입니다.

인터넷에서 TypeScript의 ‘Type Guard’에 대해 검색을 해보면, 많은 글들이 나오긴 하지만, 막상 어떤 상황에서 이를 적용할때 진가를 발휘하는지에 대한 예시가 부족한 것 같습니다.
그래서 이번 글에서는 실제 프로젝트에서 TypeScript의 Type Guard를 어떻게 활용했는지에 대해 소개하고자 합니다.

개발

프로젝트 배경

저희는 얼마전 고객사를 위한 B2B 서비스인 파트너센터를 오픈했습니다.
고객사는 파트너센터를 통해 아티스트의 채널에 공지사항을 작성하고, Push 알림을 보낼 수 있습니다.

벡엔드 로직 개발 전에, 프론트엔드와 API Spec을 정의하고,

export class CreateNoticeDto {
  title: string;
  content: string;
  ...
  notification?: {
    targets: NoticeNotificationTargetType[];
    time: number;
    ...
  };
}

DB 테이블 설계를 진행하였습니다.

@Entity('notice')
export class Notice {
  ...

  @Column()
  status: NoticeStatusType;

  @Column()
  title: string;

  @Column()
  content: string;

  @Column()
  targets?: NoticeNotificationTargetType[];

  @Column()
  time?: Date;

  ...
}

프론트엔드와의 interface에서 nested object를 사용한 이유는 notification object 전체가 필요로 하거나, 필요로 하지 않을 수 있기 때문입니다.
하지만, DB 테이블에서는 flat하게 데이터가 정리되어 들어가기 때문에 각 column 변수에 대한 optional을 각각 해석해줘야 하는 불편함이 생길 수 있습니다.
(Type Guard에 대한 내용이므로, notification에 대한 정규화 같은 것으로 내용을 확장하지는 않겠습니다.)

어떤 데이터 덩어리(데이터 구조체) 전체가 optional하게 행동을 같이 할 때 각 개별 변수를 flat하게 저장한 DB 테이블의 instance에서는 이 변수들을 만질때마다 체크(validation)해 주어야 할 수도 있습니다.

Validation의 종류

벡엔드 로직의 Guard 역할은 관심사의 Scope에 따라 다양하게 존재하는 것 같습니다.

1. Client로 부터 입력되는 비교적 상호 의존적이지 않은 개별 변수에 대한 validation은 DTO에서 처리
2. 사용자 인증은 Framework Guard에서 처리
3. 서비스 로직에서 순차적으로 진행되는 도중 class-validator 수준 이상의 복잡성을 통과한 이후에 Type Guard 사용을 권하고 싶어 이 글을 작성합니다.

Derived Type 생성

https://www.typescriptlang.org/docs/handbook/utility-types.html

export type PushableNoticeType = Omit<Notice, 'status' | 'targets' | 'time'> & {
  status: NoticeStatusType.READY;
  targets: NoticeNotificationTargetType[];
  time: Date;
};

Type Guard 적용

https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates

공지사항을 등록할 때, Push 알림을 보낼 수도 있고, 보내지 않을 수도 있습니다.
설명을 위해 nested object에 해당하는 변수를 많지 않게 설정하였지만, 더 많은 변수들이 존재한다면, 벡엔드 로직에서 점점 지저분한 코드가 될 가능성이 있습니다.
하지만 위의 PushableNoticeType과 같이, Notice으로 부터 파생되어 빈번하게 사용될 새로운 Type을 만들어, Type Guard를 적용해 보겠습니다.

isPushableNotice(notice: Notice, now: Date): notice is PushableNoticeType {
  const { status, targets, ... } = notice;

  if (!status) {
    // check status
    throw Error('status');
  }

  if (!targets) {
    // check targets
    throw Error('targets');
  }
  
  // check time
  
  return true;
}

(설명을 위해, 실제 구현에서 약간 축약 하였습니다.)

isPushableNotice 함수가 위에서 언급한 class-validator 수준 이상의 복잡성을 체크하는 일종의 validator라고 생각합니다.

---

Type Guard가 적용된 Service Logic의 흐름은 다음과 같습니다.

async pushNotice(noticeId: number, now: Date) {
  const notice = await this.noticeRepository.getNotice(noticeId);

  // 여기까지는 notice: Notice
  this.isPushableNotice(notice, now);
  // 여기부터는 notice: PushableNoticeType
  
  await this.sendNoticePush(notice, now);
}

isPushableNotice 함수 전후로 코드에서 IDE Tooltip은 다음과 같이 나타내주고 있습니다.

• isPushableNotice 함수 이전

• isPushableNotice 함수 이후

Type Guard를 사용하지 않는 상황을 상상해 보면,

어떤 서브 함수 내에서 notice.xxx에 대한 validation을 잘 했다고 해도, 그 함수를 벗어난 곳에서는 notice.xxx에 대한 validation을 다시 해주어야 합니다.
notice의 origin type(Notice)을 계속 달고 다니면서, 문제 상황마다 IDE에서 빨간 밑줄이 그어지거나, 아니면 벡엔드 로직 여기 저기서 반복적인 validation을 여러번 할 수도 있습니다.

이제까지 설명한 내용을 그림으로 표현해 봤습니다.

마치며

개인적인 견해로 TypeScript의 Type Manipulation을 통한 Type Narrowing은 정말로 매력적입니다.
Static Type을 Programming 시점에서는 Dynamic 하게 사용하는 느낌이랄까…

회사 내부 repository에서는 다음과 같은 utilities도 만들어 사용하고 있습니다.

export type WithRequiredProperty<ObjectType, Key extends keyof ObjectType> = Omit<ObjectType, Key> & {
    [Property in Key]-?: ObjectType[Property];
};

TypeScript를 사용하신다면, Type Guard, Type Manipulation으로 데이터 구조체의 타입을 최대한 좁혀 맞춤정장을 입혀 보시죠.

감사합니다.