sonamu 0.9.4 → 0.9.6

package/src/shared/web.shared.ts.txt

@@ -13,8 +13,9 @@ import type { AxiosRequestConfig } from "axios";
 import axios from "axios";
 import { EventSource } from "eventsource";
 import qs from "qs";
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { type core, z } from "zod";
+import { type InfiniteData } from "@tanstack/react-query";
 import { getCurrentLocale } from "@/i18n/sd.generated";
 
 // ISO 8601 및 타임존 포맷의 날짜 문자열을 Date 객체로 변환하는 reviver
@@ -325,8 +326,23 @@ export type SSEStreamState = {
   retryCount: number;
   isEnded: boolean;
 };
+export type WebSocketChannelOptions = {
+  enabled?: boolean;
+  retry?: number;
+  retryInterval?: number;
+  protocols?: string | string[];
+};
+export type WebSocketChannelState<TSend extends Record<string, any>> = {
+  isConnected: boolean;
+  error: string | null;
+  retryCount: number;
+  readyState: number;
+  send<K extends keyof TSend>(event: K, data: TSend[K]): void;
+  close(code?: number, reason?: string): void;
+};
+// outbound event 전체를 강제하지 않도록 handler를 optional map으로 둠
 export type EventHandlers<T> = {
-  [K in keyof T]: (data: T[K]) => void;
+  [K in keyof T]?: (data: T[K]) => void;
 };
 
 export function useSSEStream<T extends Record<string, any>>(
@@ -480,7 +496,7 @@ export function useSSEStream<T extends Record<string, any>>(
             }
 
             try {
-              const data = JSON.parse(event.data);
+              const data = JSON.parse(event.data, dateReviver);
               handler(data);
             } catch (error) {
               console.error(`Failed to parse SSE data for event ${eventType}:`, error);
@@ -501,7 +517,7 @@ export function useSSEStream<T extends Record<string, any>>(
         }
 
         try {
-          const data = JSON.parse(event.data);
+          const data = JSON.parse(event.data, dateReviver);
           // 'message' 핸들러가 있으면 호출
           const messageHandler = handlersRef.current["message" as keyof T];
           if (messageHandler) {
@@ -550,7 +566,327 @@ export function useSSEStream<T extends Record<string, any>>(
   return state;
 }
 
+export function useWebSocketChannel<
+  TReceive extends Record<string, any>,
+  TSend extends Record<string, any>,
+>(
+  url: string,
+  params: Record<string, any>,
+  handlers: EventHandlers<TReceive>,
+  options: WebSocketChannelOptions = {},
+): WebSocketChannelState<TSend> {
+  const { enabled = true, retry = 3, retryInterval = 3000, protocols } = options;
+
+  const [state, setState] = useState<Omit<WebSocketChannelState<TSend>, "send" | "close">>({
+    isConnected: false,
+    error: null,
+    retryCount: 0,
+    readyState: 3,
+  });
+
+  const socketRef = useRef<WebSocket | null>(null);
+  const retryTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const handlersRef = useRef(handlers);
+  const manualCloseRef = useRef(false);
+  // 최신 연결 식별자를 따로 두어 stale socket 이벤트가 상태를 덮지 못하게 함
+  const connectionIdRef = useRef(0);
+
+  useEffect(() => {
+    handlersRef.current = handlers;
+  }, [handlers]);
+
+  const close = (code?: number, reason?: string) => {
+    manualCloseRef.current = true;
+    if (retryTimeoutRef.current) {
+      clearTimeout(retryTimeoutRef.current);
+      retryTimeoutRef.current = null;
+    }
+    if (socketRef.current) {
+      socketRef.current.close(code, reason);
+    }
+  };
+
+  const send = <K extends keyof TSend>(event: K, data: TSend[K]) => {
+    const socket = socketRef.current;
+    if (!socket || socket.readyState !== WebSocket.OPEN) {
+      setState((prev) => ({
+        ...prev,
+        error: "WebSocket is not connected",
+      }));
+      return;
+    }
+
+    socket.send(
+      JSON.stringify({
+        event,
+        data,
+      }),
+    );
+  };
+
+  const connect = () => {
+    if (!enabled) {
+      return;
+    }
+
+    const connectionId = ++connectionIdRef.current;
+    manualCloseRef.current = false;
+
+    if (socketRef.current) {
+      socketRef.current.close();
+      socketRef.current = null;
+    }
+
+    if (retryTimeoutRef.current) {
+      clearTimeout(retryTimeoutRef.current);
+      retryTimeoutRef.current = null;
+    }
+
+    const fullUrl = resolveWebSocketUrl(url, params);
+    const socket = new WebSocket(fullUrl, protocols);
+    socketRef.current = socket;
+
+    setState((prev) => ({
+      ...prev,
+      isConnected: false,
+      error: null,
+      readyState: socket.readyState,
+    }));
+
+    // socketRef.current !== socket 가드는 이전 연결의 늦은 콜백을 무시하기 위한 장치임
+    socket.addEventListener("open", () => {
+      if (socketRef.current !== socket) {
+        return;
+      }
+
+      setState((prev) => ({
+        ...prev,
+        isConnected: true,
+        error: null,
+        retryCount: 0,
+        readyState: socket.readyState,
+      }));
+    });
+
+    socket.addEventListener("message", (event) => {
+      if (socketRef.current !== socket) {
+        return;
+      }
+
+      try {
+        const payload = JSON.parse(event.data, dateReviver) as {
+          event: keyof TReceive;
+          data: TReceive[keyof TReceive];
+        };
+        const handler = handlersRef.current[payload.event];
+        if (handler) {
+          handler(payload.data);
+        }
+      } catch (error) {
+        console.error("Failed to parse WebSocket message:", error);
+      }
+    });
+
+    socket.addEventListener("error", () => {
+      if (socketRef.current !== socket) {
+        return;
+      }
+
+      setState((prev) => ({
+        ...prev,
+        isConnected: false,
+        error: "WebSocket connection failed",
+        readyState: socket.readyState,
+      }));
+    });
+
+    socket.addEventListener("close", (event) => {
+      if (socketRef.current !== socket) {
+        return;
+      }
+
+      socketRef.current = null;
+
+      setState((prev) => ({
+        ...prev,
+        isConnected: false,
+        readyState: socket.readyState,
+      }));
+
+      if (manualCloseRef.current || connectionIdRef.current !== connectionId) {
+        return;
+      }
+
+      // 정책 위반/과대 payload close는 재시도보다 명시적 에러 노출이 우선임
+      if (!isRetryableWebSocketCloseCode(event.code)) {
+        setState((prev) => ({
+          ...prev,
+          error:
+            event.code === 1008 || event.code === 1009
+              ? `WebSocket rejected by server (code: ${event.code})`
+              : `WebSocket closed (code: ${event.code})`,
+        }));
+        return;
+      }
+
+      setState((prev) => {
+        if (prev.retryCount >= retry) {
+          return {
+            ...prev,
+            error: `Connection failed after ${retry} attempts`,
+          };
+        }
+
+        retryTimeoutRef.current = setTimeout(() => {
+          if (connectionIdRef.current !== connectionId) {
+            return;
+          }
+
+          setState((inner) => ({
+            ...inner,
+            retryCount: inner.retryCount + 1,
+          }));
+          connect();
+        }, retryInterval);
+
+        return prev;
+      });
+    });
+  };
+
+  useEffect(() => {
+    if (enabled) {
+      setState({
+        isConnected: false,
+        error: null,
+        retryCount: 0,
+        readyState: 3,
+      });
+      connect();
+    }
+
+    return () => {
+      connectionIdRef.current += 1;
+      manualCloseRef.current = true;
+      if (socketRef.current) {
+        socketRef.current.close();
+        socketRef.current = null;
+      }
+      if (retryTimeoutRef.current) {
+        clearTimeout(retryTimeoutRef.current);
+        retryTimeoutRef.current = null;
+      }
+    };
+  }, [url, JSON.stringify(params), enabled, JSON.stringify(protocols)]);
+
+  return {
+    ...state,
+    send,
+    close,
+  };
+}
+
+function isRetryableWebSocketCloseCode(code: number): boolean {
+  if (code === 1000) {
+    return false;
+  }
+
+  return ![1002, 1003, 1007, 1008, 1009].includes(code);
+}
+
+function resolveWebSocketUrl(url: string, params: Record<string, any>): string {
+  const queryString = qs.stringify(params);
+  const withQuery = queryString ? `${url}?${queryString}` : url;
+
+  if (withQuery.startsWith("ws://") || withQuery.startsWith("wss://")) {
+    return withQuery;
+  }
+
+  const baseUrl = resolveWebSocketBaseUrl();
+  return new URL(withQuery, baseUrl).toString();
+}
+
+function resolveWebSocketBaseUrl(): string {
+  const configuredBaseUrl = axios.defaults.baseURL;
+  // HTTP client와 WS client가 다른 origin으로 갈라지지 않게 axios baseURL을 우선 존중함
+  if (configuredBaseUrl) {
+    const absoluteBaseUrl =
+      typeof window !== "undefined"
+        ? new URL(configuredBaseUrl, window.location.origin).toString()
+        : configuredBaseUrl;
+    return toWebSocketBaseUrl(absoluteBaseUrl);
+  }
+
+  if (typeof window !== "undefined") {
+    return toWebSocketBaseUrl(window.location.origin);
+  }
+
+  return toWebSocketBaseUrl("$[[baseUrl]]");
+}
+
+function toWebSocketBaseUrl(baseUrl: string): string {
+  if (baseUrl.startsWith("ws://") || baseUrl.startsWith("wss://")) {
+    return baseUrl;
+  }
+
+  return baseUrl.replace(/^http:/, "ws:").replace(/^https:/, "wss:");
+}
+
 /*
   Dictionary Helper
 */
 $[[dictUtils]]
+/*
+  Query helpers
+*/
+type InfinitePage<TRow> = { rows: TRow[]; total: number };
+type DedupedInfiniteData<TRow> = InfiniteData<InfinitePage<TRow>> & {
+  rows: TRow[];
+  total: number;
+};
+
+// useInfiniteQuery의 select에 꽂아 pages/pageParams 원본은 유지하면서
+// 평탄화된 rows와 첫 페이지의 total을 data에 함께 노출합니다.
+// 각 row가 id를 갖는 경우 id 기준으로 중복 제거합니다. id가 없으면 그대로 유지합니다.
+export function dedupeAndFlatten<TRow extends { id?: unknown }>(
+  data: InfiniteData<InfinitePage<TRow>>,
+): DedupedInfiniteData<TRow> {
+  const seen = new Set<unknown>();
+  const rows: TRow[] = [];
+  for (const page of data.pages) {
+    for (const row of page?.rows ?? []) {
+      const id = row?.id;
+      if (id !== null) {
+        if (seen.has(id)) {
+          continue;
+        }
+        seen.add(id);
+      }
+      rows.push(row);
+    }
+  }
+  const total = data.pages[0]?.total ?? 0;
+  return {
+    pages: data.pages,
+    pageParams: data.pageParams,
+    rows,
+    total,
+  };
+}
+
+// TanStack Query 결과에 수동 refresh 진입점과 새로고침 중 상태를 덧붙여 줍니다.
+// isRefreshing은 query.isFetching과 독립적으로 이 함수 호출로 발생한 새로고침에 한정됩니다.
+export function useRefreshable<T extends { refetch: () => Promise<unknown> }>(
+  query: T,
+): T & { refresh: () => Promise<void>; isRefreshing: boolean } {
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const refresh = useCallback(async () => {
+    setIsRefreshing(true);
+    try {
+      await query.refetch();
+    } finally {
+      setIsRefreshing(false);
+    }
+  }, [query]);
+  return { ...query, refresh, isRefreshing };
+}