Next.js에서 react-hook-form과 URL을 우아하게 동기화하는 법 🚀

import type { AliasAny } from "@/types/alias.types";
import { isNumber } from "es-toolkit/compat";
import { useRouter, useSearchParams } from "next/navigation";
import { useCallback, useEffect, useRef } from "react";
import { type DefaultValues, type FieldValues, type UseFormProps, type UseFormReturn, useForm } from "react-hook-form";

/**
 * useFormUrlSync 훅의 옵션 타입
 * @template T - 폼 필드 값들의 타입
 */
type UseFormUrlSyncOptions<T extends FieldValues> = Omit<UseFormProps<T>, "defaultValues"> & {
  /** URL 동기화에서 제외할 필드명들 */
  excludeFromUrl?: (keyof T)[];
  /** URL 변경 시 replace 사용 여부 (기본값: true) */
  replace?: boolean;
  /** 폼의 기본값들 */
  defaultValues: DefaultValues<T>;
};

/**
 * URL 파라미터 값을 적절한 타입으로 파싱합니다.
 * @param value - 파싱할 문자열 값
 * @returns 파싱된 값 (string | number | boolean)
 */
function parseUrlValue(value: string): string | number | boolean {
  if (value === "") return value;
  if (value === "true") return true;
  if (value === "false") return false;
  const numValue = Number(value);
  if (isNumber(numValue) && !Number.isNaN(numValue)) {
    return numValue;
  }
  return value;
}

/**
 * URL 검색 파라미터에서 초기값을 추출합니다.
 * @template T - 폼 필드 값들의 타입
 * @param searchParams - URL 검색 파라미터
 * @param excludeFromUrl - URL 동기화에서 제외할 필드명들
 * @returns URL에서 추출한 초기값들
 */
function extractInitialValuesFromUrl<T extends FieldValues>(
  searchParams: URLSearchParams,
  excludeFromUrl: (keyof T)[],
): Partial<T> {
  const urlValues: Partial<T> = {};
  for (const [key, value] of searchParams.entries()) {
    if (!excludeFromUrl.includes(key as keyof T)) {
      (urlValues as AliasAny)[key] = parseUrlValue(value);
    }
  }
  return urlValues;
}

/**
 * 폼 값들로부터 URL 파라미터를 생성합니다.
 * @template T - 폼 필드 값들의 타입
 * @param values - 폼 값들
 * @param currentParams - 현재 URL 파라미터
 * @param excludeFromUrl - URL 동기화에서 제외할 필드명들
 * @returns 새로운 URLSearchParams 객체
 */
function createUrlParamsFromValues<T extends FieldValues>(
  values: T,
  currentParams: URLSearchParams,
  excludeFromUrl: (keyof T)[],
): URLSearchParams {
  const params = new URLSearchParams(currentParams);
  for (const [key, value] of Object.entries(values)) {
    if (excludeFromUrl.includes(key as keyof T)) {
      continue;
    }
    if (value !== undefined && value !== null && value !== "") {
      params.set(key, String(value));
    } else {
      params.delete(key);
    }
  }
  return params;
}

/**
 * 두 객체의 깊은 비교를 수행합니다.
 * @param obj1 - 비교할 첫 번째 객체
 * @param obj2 - 비교할 두 번째 객체
 * @returns 객체들이 동일한지 여부
 */
function deepEqual(obj1: AliasAny, obj2: AliasAny): boolean {
  return JSON.stringify(obj1) === JSON.stringify(obj2);
}

/**
 * React Hook Form과 URL 검색 파라미터를 양방향으로 동기화하는 커스텀 훅입니다.
 *
 * @template T - 폼 필드 값들의 타입, FieldValues를 확장해야 함
 * @param options - 훅 설정 옵션
 * @returns React Hook Form의 UseFormReturn 객체
 *
 * @remarks
 * URL 파라미터는 자동으로 적절한 타입(string, number, boolean)으로 파싱됩니다.
 * 빈 문자열, null, undefined 값은 URL에서 제거됩니다.
 * Next.js의 useRouter와 useSearchParams를 사용하므로 Next.js 환경에서만 동작합니다.
 */
export function useFormUrlSync<T extends FieldValues>(options: UseFormUrlSyncOptions<T>): UseFormReturn<T> {
  const router = useRouter();
  const searchParams = useSearchParams();
  const { excludeFromUrl = [], replace = true, defaultValues, ...formOptions } = options;
  
  const isUpdatingFromUrl = useRef(false);

  const getUrlValues = useCallback(() => {
    return extractInitialValuesFromUrl<T>(searchParams, excludeFromUrl as (keyof T)[]);
  }, [searchParams, excludeFromUrl]);

  const initialValues = {
    ...defaultValues,
    ...getUrlValues(),
  } as DefaultValues<T>;

  const form = useForm({
    ...formOptions,
    defaultValues: initialValues,
  });

  const { watch, reset, getValues } = form;

  const updateUrl = useCallback(
    (values: T) => {
      const params = createUrlParamsFromValues(values, searchParams, excludeFromUrl as (keyof T)[]);
      const newSearchString = params.toString();
      const currentSearchString = new URLSearchParams(window.location.search).toString();

      if (newSearchString !== currentSearchString) {
        const newUrl = `${window.location.pathname}?${newSearchString}`;
        if (replace) {
          router.replace(newUrl, { scroll: false });
        } else {
          router.push(newUrl, { scroll: false });
        }
      }
    },
    [router, searchParams, excludeFromUrl, replace],
  );

  useEffect(() => {
    const subscription = watch(values => {
      if (isUpdatingFromUrl.current) {
        return;
      }
      updateUrl(values as T);
    });

    return () => subscription.unsubscribe();
  }, [watch, updateUrl]);

  useEffect(() => {
    const urlValues = getUrlValues();
    const currentFormValues = getValues();

    const relevantFormValues: Partial<T> = {};
    for (const key in urlValues) {
      if (Object.prototype.hasOwnProperty.call(urlValues, key)) {
        relevantFormValues[key as keyof T] = currentFormValues[key as keyof T];
      }
    }

    if (!deepEqual(urlValues, relevantFormValues)) {
      isUpdatingFromUrl.current = true;

      reset({
        ...currentFormValues,
        ...urlValues,
      } as DefaultValues<T>);

      setTimeout(() => {
        isUpdatingFromUrl.current = false;
      }, 0);
    }
  }, [getUrlValues, reset, getValues]);

  return form;
}

  // ...

  useEffect(() => {
    const subscription = watch(values => {
      // isUpdatingFromUrl 플래그에 대해서는 잠시 후에 설명하겠습니다.
      if (isUpdatingFromUrl.current) {
        return;
      }
      updateUrl(values as T); // 폼 값이 변경되면 URL을 업데이트하는 함수 호출
    });

    return () => subscription.unsubscribe();
  }, [watch, updateUrl]);

  // ...

  // ...

  useEffect(() => {
    const urlValues = getUrlValues(); // URL에서 현재 폼 관련 값들을 가져옴
    const currentFormValues = getValues(); // react-hook-form의 현재 값들을 가져옴

    // ... (비교 로직) ...

    // URL의 값과 폼의 값이 다를 경우
    if (!deepEqual(urlValues, relevantFormValues)) {
      isUpdatingFromUrl.current = true; // 무한 루프 방지 플래그 ON

      // URL 값으로 폼 상태를 리셋(업데이트)
      reset({
        ...currentFormValues,
        ...urlValues,
      } as DefaultValues<T>);

      // 아주 잠깐의 딜레이 후 플래그 OFF
      setTimeout(() => {
        isUpdatingFromUrl.current = false;
      }, 0);
    }
  }, [getUrlValues, reset, getValues]); // URL이 변경될 때마다 실행

// components/SearchForm.tsx
"use client";

import { useFormUrlSync } from "@/hooks/useFormUrlSync"; // 우리가 만든 훅

interface SearchFormValues {
  keyword: string;
  category: string;
  inStockOnly: boolean;
  page: number;
}

export function SearchForm() {
  const { register, handleSubmit, formState: { errors } } = useFormUrlSync<SearchFormValues>({
    // 폼의 기본값 설정
    defaultValues: {
      keyword: "",
      category: "all",
      inStockOnly: false,
      page: 1,
    },
    // URL에 포함시키고 싶지 않은 필드
    excludeFromUrl: ["page"],
    // URL 변경 시 히스토리를 남기고 싶을 때
    replace: false,
  });

  const onSubmit = (data: SearchFormValues) => {
    // 실제 검색 로직 수행
    console.log("검색 실행:", data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <div>
        <label htmlFor="keyword">검색어</label>
        <input id="keyword" {...register("keyword")} />
      </div>
      <div>
        <label htmlFor="category">카테고리</label>
        <select id="category" {...register("category")}>
          <option value="all">전체</option>
          <option value="electronics">전자기기</option>
          <option value="books">도서</option>
        </select>
      </div>
      <div>
        <input type="checkbox" id="inStockOnly" {...register("inStockOnly")} />
        <label htmlFor="inStockOnly">재고 있음</label>
      </div>
      <button type="submit">검색</button>
    </form>
  );
}