Zod + RHF를 사용할때, Discriminated Union vs Optional Fields

[dh-lim1]

논의하고 싶은 주제 소개를 위해 예시를 재구성 해보았습니다.

---

우리는 광고 소재를 관리하는 폼을 만듭니다.
최초의 요구사항은 다음과 같습니다.

???: "소재는 topText, bottomText, image를 가져요!"

이에 최초 타입을 후다닥 다음과 같이 정의하게 되었어요.

const CreativeSchema = z.object({
    id: z.number(),
    topText: z.string(),
    bottomText: z.string(),
    image: z.string(),
    landingUrl: z.string()
})

나: 🙂

한 달 후

???: "타입을 추가하고 싶어요! 기존 소재는 A타입이라고 하고,
B타입일 때는 추가로 closeButton, middleText를 갖게 해주세요."

const CreativeSchema = z.object({
    id: z.number(),
    type: z.enum(['A', 'B']),
    topText: z.string(),
    bottomText: z.string(),
    image: z.string(),
    closeButton: z.string().optional(),
    middleText: z.string().optional(),
    landingUrl: z.string()
})

나: 😒

두 달 후

???: "image는 없고 topText, middleText, bottomText로만 구성된 C타입을 추가합시다!"

const CreativeSchema = z.object({
    id: z.number(),
    type: z.enum(['A', 'B', 'C']),
    topText: z.string(),
    bottomText: z.string(),
    image: z.string().optional(),
    closeButton: z.string().optional(),
    middleText: z.string().optional(),
    landingUrl: z.string()
})

나: 😕

세 달 후

???: "B 타입은 bottomText가 없으면 자동으로 뱃지를 추가하려구요. bottomText를 null도 받을 수 있게 변경해주세요."

const CreativeSchema = z.object({
    id: z.number(),
    type: z.enum(['A', 'B', 'C']),
    topText: z.string(),
    bottomText: z.string().nullable(),
    image: z.string().optional(),
    closeButton: z.string().optional(),
    middleText: z.string().optional(),
    landingUrl: z.string(),
})

나: 😟

여섯 달 후

???: "접었다 펼 수 있는 D타입을 추가할거에요. 이거 CTR 30% 찍을 수 있대요. 아참, 이건 접었을 때랑 폈을 때랑 랜딩 페이지가 달라요."

const CreativeSchema = z.object({
    id: z.number(),
    type: z.enum(['A', 'B', 'C', 'D']),
    topText: z.string(),
    bottomText: z.string().nullable(),
    image: z.string().optional(),
    closeButton: z.string().optional(),
    middleText: z.string().optional(),
    isExpanded: z.boolean().optional(),
    landingUrl: z.string(),
    expandedLandingUrl: z.string().optional()   
})

나: 😡

마침 새로 합류한 팀원이 묻습니다.

👶 : "여기 bottomText는 언제 nullable이에요?"

Discriminated Union으로 리팩토링

이쯤되면 아차! 싶습니다.
빠르게 리팩토링 시간을 갖고 타입을 Discriminated Union로 변경합니다.

const SharedSchema = z.object({
    id: z.number(),
    ....
})

const AType = z.object({
    type: z.literal('A'),
    topText: z.string(),
    bottomText: z.string(),
    image: z.string(),
    landingUrl: z.string(),
})

const BType = z.object({
    type: z.literal('B'),
    topText: z.string(),
    bottomText: z.string().nullable(),
    image: z.string(),
    closeButton: z.string(),
    middleText: z.string(),
    landingUrl: z.string(),
})

const CType = z.object({
    type: z.literal('C'),
    topText: z.string(),
    bottomText: z.string(),
    middleText: z.string(),
    image: z.string(),
    landingUrl: z.string(),
})

const DType = z.object({
    type: z.literal('D'),
    topText: z.string(),
    bottomText: z.string(),
    image: z.string(),
    closeButton: z.string(), 
    middleText: z.string(),
    isExpanded: z.boolean(),
    landingUrl: z.string(),
    expandedLandingUrl: z.string()
})

const CreativeSchema = z.discriminatedUnion('type', [AType, BType, CType, DType]).and(SharedSchema)

비록 타입이 추가될 때마다 추가되는 코드의 양은 늘겠지만, 타입별 필드가 명확하게 구분되었고, 런타임 validation도 훨씬 견고해졌습니다.

하지만...

???: "소재별로 동일한 공통 특징이 있는 애들끼리 그룹으로 묶어서 관리해야겠어요"

const GroupSchema = z.object({
    id: z.number(),
    creatives: z.array(CreativeSchema),
})

우리는 RHF을 가지고 이 스키마 타입을 기반으로 이제 폼을 그려야합니다.

type Group = z.infer<typeof GroupSchema>;

const { control, register } = useForm<Group>();
const { fields } = useFieldArray({
  control,
  name: 'creatives',
});

{fields.map((field, index) => (
    <input {...register(`creatives.${index}.expandedLandingUrl`)} /> // Error !!
    // Property 'expandedLandingUrl' does not exist on type 'FieldArrayWithId<~~>'.
))}

오잉? 추론된 field가 초라해졌어요. 무소유라도 실천하는 걸까요.

왜 이런 일이 일어났을까?

z.infer는 discriminatedUnion이기 때문에
타입스크립트는 field의 타입을 AType | BType | CType | DType 의 union으로 간주하게 됩니다.

그런데 useFieldArray에서의 fields는 내부적으로 FieldArrayWithId 타입을 따르며,
여기서는 공통 필드만 추론되도록 좁은 타입 추론이 일어나게 됩니다.

그 결과:

• expandedLandingUrl 같은 D타입 전용 필드는 존재하지 않는 것으로 간주됨
• 타입 추론이 무너지고, 자동완성과 타입 오류가 발생하지 않음 → DX 급감

해결?

{fields.map((field) => (
    <div key={field.id}>{(field as DType).expandedLandingUrl}</div>
))}

function isDType(creative: typeof fields[number]): creative is DType {
  return creative.type === 'D';
}

{fields.map((field, index) => {
  if (isDType(field)) {
    return (
      <input {...register(`creatives.${index}.expandedLandingUrl`)} />
    );
  }

  return null;
})}

위처럼 타입 분기처리를 하거나, type assertion, type guard를 사용하는 방법으로 해결할 수 있겠으나,
이런 방법을 하려고 내가 리팩토링을 했나 현타가 옴과 동시에 Discriminated Union이 정말 최선인가? 생각이 듭니다. (과거로 돌아가 optional chaining을 남발하고 싶은 욕구도 치솟습니다.)

논의해보고 싶은 지점들

다들 유사한 경험이 있으실 것 같아요.

1. 이렇게 폼의 구조가 점점 복잡해지는 상황에서 어떻게 스키마를 관리하고 계신가요?
   1.1 리팩토링 결정하는 시점은 언제인가요?
   1.2 리팩토링 시점에 대한 판단 기준은 무엇인가요?
2. discriminatedUnion 사용 시 타입 추론이 깨지는 문제를 해결하는 가장 좋은 방법은 무엇일까요?
3. 다른 방법으로 풀어낸 경험이 있으면 알려주세요!

[Hankpkj]

저도 비슷한 경험이 있었고, 결국 Discriminated Union + type guard 조합으로 갔습니다.
zod 스키마 자체가 일종의 명세 역할을 해주기 때문에 문서나 Swagger 없이도 구조적 가이드가 가능하다는 장점이 있고요.

타입 추론이 깨지는 부분은 TS 제너릭의 한계라 어쩔 수 없는 것 같고, RHF에서 as 또는 type guard를 써서 해결하긴 했습니다.

폼 복잡도가 더 올라갈 경우에는 타입별 폼 컴포넌트를 분리하고, switch-case나 registry 패턴으로 대응하는 것도 추천드려요!

{fields.map((field, index) => {
  switch (field.type) {
    case 'D':
      return <DTypeCreativeForm field={field} index={index} />;
    case 'A':
      return <ACreativeForm field={field} index={index} />;
    ...
  }
})}