react-table-mapping

react-table-mapping 패키지를 소개합니다!

어쩌다 직접 만들었나

올해 5월 부터, 팀 내부에서 차세대 UI 개편 프로젝트 Version 2 를 진행하며, 몇 개의 라이브러리가 React 19 버전으로 올라오며, 버전 호환 문제로 동일한 라이브러리를 쓰는데에 제약사항이 있었습니다.

나: 팀장님, 저희 기존 라이브러리 몇 개가 React 19 버전으로 올라오면서, 버전 호환
문제로 동일한 라이브러리를 쓰는데에 제약사항이 있는데 어떻게 하면 좋을까요?

팀장님: 직접 만들어봐.

나: 네.

나: (네?)

당황스러웠지만, 오픈소스 패키지를 직접 만들어보는 것 또한 재밌을 것 같아, 직접 만들어보기로 하였습니다. 그렇게 완성된 저의 첫번째 오픈소스 패키지는 바로 !!

react-table-mapping 이라는 패키지 입니다.

DEMO

데모링크

간단하게 시작 지점의 테이블의 각 로우와, 끝 지점의 테이블의 각 로우를 드래그 앤 드롭으로 매핑할 수 있는 GUI 컴포넌트입니다. 많은 수정과 시행착오가 있어 무수히 많은 베타버전이 존재하지만.. 현재는 해당 라이브러리를 팀 내부에서 적용 완료한 상태며, 곧 버전 1.0.0 으로 배포할 예정입니다 😀

---

동작 방식

어떤 방식으로 동작을 해야할까?

첫번째로 구현한 방식 - 의존성 배열의 문제 🔥

처음에는 단순히 사용자 관점이 아닌, 라이브러리를 만드는 입장에서만 생각했습니다. 프로젝트 초기 당시 기간이 촉박해 빨리 만들어야겠다는 생각만 강했던 것 같습니다.

맵핑에 필요한 상태를 한 곳에서 관리하기 위해 Provider를 만들어 상태를 관리했습니다.

그리고 같은 라인 맵핑하기, 동일한 이름 맵핑하기, 라인 다시 그리기 등 모든 기능을 커스텀 훅으로 만들어 사용자들이 쓸 수 있게 하자는 취지로 진행했습니다.

세 달간 열심히 개발하고 Provider를 포함한 라이브러리가 완성되었습니다.

이를 적용하기 위해 출근해서 npm registry에 배포된 패키지를 설치하고 적용하던 중, Maximum rerender... 바로 무한 루프에 빠져버렸습니다.

원인은 의존성 배열 문제였습니다.

useEffect(() => {
  updateSourceFields(sourceFieldsFromProps)
}, [sourceFieldsFromProps]) // 사용하는 쪽의 상태가 계속 바뀌기 때문에 무한루프

두번째로 구현한 방식 - 설계 실패로 인한 상태 동기화 문제 🔥

그렇게 도달한 두 번째 결과는..

useEffect 훅을 사용하되, 의존성 배열을 빈 배열로 작성하여, 초기 상태 (sources, targets, initialMappings) 만 주입하고, 라이브러리 내부에서 상태를 모두 관리하여, onMappingChange 라는 props로 변경된 상태를 알 수 있게 하자!

였습니다.

<TableMappingProvider>
  <TableMapping
    lineType="bezier"
    sourceColumns={sourceColumns}
    targetColumns={targetColumns}
    sources={sourceFields}
    targets={targetFields}
    initialMappings={initialMappings}
    onMappingChange={(mappings) => {
      console.info("mappings", mappings)
    }}
  />
</TableMappingProvider>

예를 들어 위와 같이 사용하면, 라이브러리 내부에서 상태를 모두 관리하고, onMappingChange 라는 props로 변경된 상태를 알 수 있게 하였습니다.

이렇게 개선하니, 초기 호출에는 무한 루프에 빠지지 않고 잘 동작하였습니다.

그러나..

onMappingChange={(mapping) =>
  setSomethingState((prev) => ({ ...prev, mapping }))
}

위와 같이 사용하며 사용하는 쪽과 라이브러리 내부 상태의 싱크를 맞추며 개발하던 중, 라이브러리에서 제공하는 hook으로 라이브러리 내부 상태와 사용하는 쪽 상태를 동시에 바꾸게 되니,

또 다시 찾아온  Maximum rerender... 바로 무한 루프 😇

두 번째 이슈를 겪고 나니, 처음으로 돌아가 초기 설계부터 다시 생각해보게 되었습니다.

원인 분석

개발하기 전, 자신에게 던졌던 요구사항은 다음과 같습니다.

1. 사용자가 라이브러리 hook을 사용하여 상태 변경 및 Mapping UI 변경 행위를 할 수 있었으면 좋겠다.
2. 라이브러리 내부 mapping 상태가 변경될 때 마다 사용자가 알 수 있었으면 좋겠다.
3. 대표적인 액션 (mapping, update, remove) 시에, 전처리, 후처리 기능이 있었으면 좋겠다.

그리고 구상했던 프로세스는 아래와 같습니다.

구상했던 프로세스 😀

1. 사용자 이벤트 (드래그&드롭, onChange 등)

   ↓

2. 라이브러리 내부 상태 변경

   ↓

3. props로 전달 받은 onMappingChange 콜백 호출

   ↓

4. 부모 컴포넌트의 상태 업데이트 (setSomethingState)

   ↓

5. UI 변경

문제가 됐던 프로세스 😇

1. 사용자 이벤트 발생

   ↓

2. 라이브러리에서 제공하는 hook 호출 (ex: onBeforeMappingChange)

   ↓

3. hook에서 라이브러리 내부 상태 변경 + 부모 상태 변경 동시 발생

   ↓

4. onMappingChange 콜백 호출

   ↓

5. 부모 컴포넌트 상태 업데이트 (setSomethingState)

   ↓

6. 부모 리렌더링으로 새로운 props 전달

   ↓

7. 라이브러리 내부에서 props 변경 감지

   ↓

8. 다시 상태 동기화 시도

   ↓

9. 7 ~ 8번 프로세스 무한 반복

   ↓

10. Maximum rerender…

문제점 분석

원인을 분석하고 나서, 다른 라이브러리의 상태는 어떻게 관리되고 있을까… 생각하게 되었습니다.

그리고 자주 사용하는 라이브러리인 react-hook-form 이라는 패키지가 떠올랐고, 제어 컴포넌트와 비제어 컴포넌트 관점에서 생각해보게 되었습니다.

핵심 문제점들

1. 상태 소유권의 모호함이 존재했습니다.

// 라이브러리 내부 상태
const [internalMappings, setInternalMappings] = useState(initialMappings)
 
// 사용자 측 상태
const [userMappings, setUserMappings] = useState(initialMappings)
 
// 문제: 상태 동기화가 힘들고, 무한렌더의 주요원인이 되었습니다.

어떤 상태가 실제 데이터인지 명확하지 않았기에, 두 상태 간 동기화 과정에서 많은 충돌이 발생했습니다.

2. 나도 모르게 React 에서 양방향 데이터 바인딩을 시도해버린 케이스

1번의 문제점을 파악하고 나니, 단방향 데이터 흐름을 지향하는 React에서 자신도 모르게 양방향 데이터 바인딩을 추구해버렸다고 생각도 들었습니다.

//library hooks
const { updateSourceFields } = useTableMapping()
 
//local state
const [newSourceFields, setNewSourceFields] = useState<SourceFields>({
  //..
})
 
const handleSomeAction = (sourceFields: SourceFields) => {
  updateSourceFields(sourceFields) // 1. 라이브러리 내부 상태 변경
  setNewSourceFields(sourceFields) // 2. 사용자 측 지역 상태 변경
}

위의 코드와 같이 작성하고 있었는데, 양방향으로 상태를 동기화하려다 보니, 상태 변경이 연쇄적으로 발생하여 무한 루프의 주된 원인이 되었던 것 같았습니다.

내린 결론

취업 준비 시절 사용해봤던 상태 관리 라이브러리인 Redux 라는 패키지를 생각해보게 되었습니다.

Redux는 View 컴포넌트에서 전역 상태를 구독하고, Dispatch 함수를 통해 특정 Action type과 변경할 상태, 즉 payload를 보내어 데이터를 업데이트 하는 Flux 아키텍처를 지향합니다.

Action → Dispatcher → Store → View
  ↑                           ↓
  └─────── User Interaction ──┘

Flux 아키텍처 의 핵심은 단방향 데이터 흐름 이기에, 라이브러리에 비슷한 형식으로 적용해보기로 하였습니다.

적용해보기

Hook 제공 방식 변경

기존 useTableMapping을 호출하여 hook을 사용하던 방식에서, ref를 받아 사용하는 방식으로 개선하였습니다.

이유는 아래와 같았습니다.

1. Provider 제거로 인한 useTableMapping을 사용하고 있는 컴포넌트의 불필요한 렌더링 방지될 것이다..
2. 보일러 플레이트 코드가 감소할 것이다.
3. 부모 컴포넌트에서 직접적으로 라이브러리를 제어하며, 호출해도 onMappingChange로 변경된 상태만 전달되기 때문에, 무한렌더링을 방지할 수 있을 것이다

<AddButton
  variant="outline"
  onClick={() => {
	if (tableMappingRef.current) {
	  tableMappingRef.current.appendSource(generateSourceDefaultValue());
	}
  }}
>

실제로 위와 같이 사용할 수 있게 되었습니다 😀

상태 관리의 개선

데이터가 단방향으로 흐를 수 있게 개선하였습니다.

라이브러리 내부에서는 상태를 관리하지 않으며, 특정 Action이 일어났을 시, Action type과 변경된 상태를 담고 있는 Payload를 사용하는 측으로 전달합니다.

const useTableMapping = ({
  sources: sourcesFromProps,
  targets: targetsFromProps,
  mappings: mappingsFromProps,
  onStateChange,
}: UseTableMappingProps) => {
  const sourceFields = sourcesFromProps as FieldItem[]
  const targetFields = targetsFromProps as FieldItem[]
  const mappings = mappingsFromProps
 
  const notifyChange = (
    newSources: FieldItem[],
    newTargets: FieldItem[],
    newMappings: Mapping[],
    action: NotifyAction,
  ) => {
    onStateChange({
      sources: newSources,
      targets: newTargets,
      mappings: newMappings,
      action,
    })
  }
 
  //...
}

위와 같이, 라이브러리에서 제공하는 api를 호출하거나, 라이브러리 내부에서 상태 변화가 일어났을 시, 내부적으로 notifyChange라는 함수를 호출하고, 최종적으로 onMappingChange 로만 변경된 상태가 전달됩니다

예를 들어, 모든 맵핑을 제거하기 위해 다음과 같이 호출하게 되었습니다.

<TrashButton
  variant="outline"
  className="border-[var(--color-border-default)]"
  onClick={() => {
	if (tableMappingRef.current) {
	  tableMappingRef.current.clearMappings();
	}
  }}
>

그러면 onMappingChange로 아래와 같은 상태가 전달되게 됩니다 😀

<TableMapping
  //..
  onMappingChange={(stateWithAction) => {
    const { sources, targets, mappings, action } = stateWithAction;
 
    console.log(stateWithAction);
 
	// sources: 변경된 sources
	// targets: 변경된 targets
	// mappings: 변경된 mappings
	// action: {
	//   type: 'REMOVE_MAPPING',
	//   paload: {
	//      mappingId: string;
    //      removedMapping: Mapping | undefined;
	//   }
    // }
 }
/>

그렇게 완성된 결과물 .. 📚

활성화 상태

비활성화 상태

---

느낀 점 🤵

이번 라이브러리 개발을 통해 React의 상태 관리에 대해 더 깊게 생각해보게 된 계기가 되었습니다. 처음에는 단순히 "빨리 만들어야 한다" 는 생각으로 접근했지만, 무한 렌더링이라는 이슈에 부딪히면서 근본적인 설계의 중요성을 깨달았습니다.

특히 단방향 데이터 흐름에서의 상태를 누가 관리하는가 라는 개념이 얼마나 중요한지 알게 되었습니다.

초기에 설계했던 구조는, 개선 후 생각해보니 사람 두 명이, 자동차 핸들을 쥐고 서로 좌우로 돌리는 느낌이였던 것 같습니다.

이번 react-table-mapping 패키지 개선 이후, 다른 패키지를 만들게 되는 날이 오면, 처음부터 명확한 상태 관리 전략을 수립하고, 사용자 관점에서의 개발자 경험을 우선적으로 고려해야겠다는 다짐을 하였습니다.

이상으로 오늘 포스팅을 마치겠습니다 !