sonamu 0.9.4 → 0.9.6

package/src/api/websocket-helpers.ts

@@ -0,0 +1,122 @@
+import { type Server } from "http";
+
+import { type WebsocketPluginOptions } from "@fastify/websocket";
+import { type FastifyReply } from "fastify";
+
+import { isSoException } from "../exceptions/so-exceptions";
+import { isPlainObject } from "../utils/utils";
+import { type ExtendedApi } from "./decorators";
+
+// Fastify websocket route와 Vite HMR websocket이 같은 server socket을 두고 충돌하는 것을 방지하기 위해,
+// WS route가 존재하면 HMR을 별도 포트로 분리해 띄움
+export function resolveIntegratedViteHmrOptions({
+  httpServer,
+  requiresDedicatedWebSocketServer,
+  rawPort = process.env.SONAMU_VITE_HMR_PORT,
+}: {
+  httpServer: Server;
+  requiresDedicatedWebSocketServer: boolean;
+  rawPort?: string | undefined;
+}): { server: Server } | { port: number } {
+  if (!requiresDedicatedWebSocketServer) {
+    return { server: httpServer };
+  }
+
+  const parsedPort = rawPort?.trim() ? Number(rawPort) : 24678;
+  return Number.isFinite(parsedPort) && parsedPort > 0 ? { port: parsedPort } : { port: 24678 };
+}
+
+// route-level maxPayload를 서버 plugin options으로 승격시켜, 큰 frame을 받은 뒤 닫는 대신
+// transport 레벨에서 먼저 제한되도록 함
+export function resolveWebSocketPluginOptions({
+  rawPluginOption,
+  apis,
+}: {
+  rawPluginOption: boolean | WebsocketPluginOptions | undefined;
+  apis: ExtendedApi[];
+}): WebsocketPluginOptions | undefined {
+  const pluginOptions =
+    rawPluginOption && rawPluginOption !== true
+      ? { ...rawPluginOption }
+      : ({} as WebsocketPluginOptions & { maxPayload?: number });
+  const serverOptions = isPlainObject(pluginOptions.options)
+    ? { ...pluginOptions.options }
+    : ({} as NonNullable<WebsocketPluginOptions["options"]>);
+
+  if (isPositiveNumber(pluginOptions.maxPayload) && serverOptions.maxPayload === undefined) {
+    serverOptions.maxPayload = pluginOptions.maxPayload;
+    delete pluginOptions.maxPayload;
+  }
+
+  if (serverOptions.maxPayload === undefined) {
+    const routeMaxPayloads = apis
+      .map((api) => api.websocketOptions?.maxPayload)
+      .filter(isPositiveNumber);
+
+    if (routeMaxPayloads.length > 0) {
+      serverOptions.maxPayload = Math.max(...routeMaxPayloads);
+    }
+  }
+
+  if (Object.keys(serverOptions).length > 0) {
+    pluginOptions.options = serverOptions;
+  }
+
+  return Object.keys(pluginOptions).length > 0 ? pluginOptions : undefined;
+}
+
+// handshake/auth/validation 실패를 generic 1011로 뭉개지 않고 1008(policy violation)로 매핑해,
+// close code policy를 한 곳에서 정의함
+export function resolveWebSocketCloseDescriptor(error: unknown): {
+  code: number;
+  reason: string;
+  logLevel: "warn" | "error";
+} {
+  if (isSoException(error)) {
+    if (error.statusCode === 400) {
+      return {
+        code: 1008,
+        reason: "Invalid websocket handshake",
+        logLevel: "warn",
+      };
+    }
+
+    if (error.statusCode === 401 || error.statusCode === 403) {
+      return {
+        code: 1008,
+        reason: "Unauthorized websocket connection",
+        logLevel: "warn",
+      };
+    }
+
+    if (error.statusCode >= 400 && error.statusCode < 500) {
+      return {
+        code: 1008,
+        reason: "Rejected websocket connection",
+        logLevel: "warn",
+      };
+    }
+  }
+
+  return {
+    code: 1011,
+    reason: "WebSocket handler failed",
+    logLevel: "error",
+  };
+}
+
+// WS 경로에서는 reply가 존재하지 않으므로 접근 시도를 즉시 에러로 surface해 transport misuse를 빨리 드러냄
+// SSE/reply에 의존하는 contextProvider가 있으면 websocketContextProvider를 따로 정의하라는 가이드 역할도 함
+export function createWebSocketReplyStub(): FastifyReply {
+  return new Proxy({} as FastifyReply, {
+    get() {
+      throw new Error(
+        "FastifyReply is not available in websocket context. Define websocketContextProvider if your context setup depends on reply mutation.",
+      );
+    },
+  });
+}
+
+function isPositiveNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}

package/src/bin/cli.ts

@@ -228,9 +228,17 @@ bootstrap().finally(async () => {
 /**
  * pnpm sync 하면 실행되는 함수입니다.
  * 프로젝트를 싱크합니다.
+ *
+ * `--force` 옵션이 주어지면 lock을 무시하고 풀-싱크를 수행합니다.
+ * git post-merge hook이나 CI에서 매 pull 후 자동 실행할 수 있도록 노출.
  */
 async function sync() {
-  await Sonamu.syncer.sync();
+  const { flags } = parseCliOptions();
+  if (flags.has("force")) {
+    await Sonamu.syncer.forceSync();
+  } else {
+    await Sonamu.syncer.sync();
+  }
 }
 
 /**
@@ -265,7 +273,7 @@ function spawnApiDevServer(options?: { extraEnv?: Record<string, string> }) {
       "--node-args=--enable-source-maps", // 그리고 소스맵 지원을 위한 플래그입니다.
       "--on-key=r:restart:Restart server", // r 누르면 서버 재시작하게 해줘요.
       "--on-key=c:clear:Clear screen", // c 누르면 터미널 화면을 지워줘요.
-      `--on-key=f:shell(rm ${path.join(apiRoot, "sonamu.lock")}):restart:Force restart`, // f 누르면 sonamu.lock 파일을 지우고 서버 재시작하게 해줘요.
+      `--on-key=f:shell(rm ${path.join(apiRoot, "sonamu.lock")}):restart:Force restart`, // f 누르면 lock 제거 후 재시작 → 새 프로세스가 부트스트랩에서 풀-싱크. force sync CLI를 shell로 부르면 살아있는 서버의 watcher 폭풍이 :restart와 충돌해 상태 이상.
 
       "--on-key=enter:shell(echo hi):Key binding test", // enter를 key로 쓸 수 있음을 보이기 위한 테스트입니다.
       "--on-key=ctrl+f ctrl+f:shell(git pull && pnpm install && pnpm --filter sonamu build && echo 'Sonamu is now up-to-date!'):restart:Pull & install & build & restart", // modifier와의 조합, 그리고 두 개의 chord를 사용할 수 있음을 보이기 위한 테스트입니다.

package/src/database/upsert-builder.ts

@@ -310,7 +310,7 @@ export class UpsertBuilder {
 
         // uuid를 별도로 보관하고, DB에 저장할 데이터에서 제거
         const originalUuids = dataChunk.map((r) => r.uuid as string);
-        const dataForDb = dataChunk.map(({ uuid, ...rest }) => rest);
+        const dataForDb = dataChunk.map(({ uuid: _, ...rest }) => rest);
 
         let resultRows: { id: number | string; [key: string]: unknown }[];
 
@@ -331,7 +331,7 @@ export class UpsertBuilder {
               for (const row of rowsWithoutId) {
                 const values = columns.map((col) => row[col]);
                 // null이 포함된 조건은 제외 (PostgreSQL UNIQUE는 NULL 무시)
-                if (!values.some((v) => v == null)) {
+                if (!values.some((v) => v === null || v === undefined)) {
                   conditions.push(values);
                 }
               }
@@ -448,7 +448,7 @@ export class UpsertBuilder {
 
       // 현재 register된 레코드들의 FK 값들 추출
       const fkConditions = fkColumns.map((fkCol) => {
-        const fkValues = [...new Set(table.rows.map((row) => row[fkCol]).filter((v) => v != null))];
+        const fkValues = [...new Set(table.rows.map((row) => row[fkCol]).filter(Boolean))];
         return { column: fkCol, values: fkValues };
       });
 

package/src/dict/sonamu-dictionary.ts

@@ -296,7 +296,7 @@ export class SonamuDictionary {
 
     // 파일 재생성
     const content = this.generateProjectDict(locale, existingEntries, isDefaultLocale);
-    const formatted = await formatCode(content, "typescript", filePath);
+    const formatted = await formatCode(content, filePath);
     fs.writeFileSync(filePath, formatted, "utf-8");
   }
 
@@ -418,7 +418,7 @@ export class SonamuDictionary {
     const i18nDir = this.ensureI18nDir();
     const dictPath = path.join(i18nDir, `${locale}.ts`);
     const content = this.generateProjectDict(locale, entries, isDefaultLocale);
-    const formatted = await formatCode(content, "typescript", dictPath);
+    const formatted = await formatCode(content, dictPath);
     fs.writeFileSync(dictPath, formatted, "utf-8");
   }
 
@@ -631,7 +631,7 @@ export class SonamuDictionary {
     const stats: Record<string, { total: number; filled: number; percent: number }> = {};
     const total = rows.length;
     for (const locale of locales) {
-      const filled = rows.filter((row) => row[locale] != null && row[locale] !== "").length;
+      const filled = rows.filter((row) => !!row[locale]).length;
       const percent = total > 0 ? Math.round((filled / total) * 100) : 0;
       stats[locale] = { total, filled, percent };
     }

package/src/entity/entity.ts

@@ -943,7 +943,7 @@ export class Entity {
       `src/application/${this.names.parentFs}/${this.names.fs}.entity.json`,
     );
     const json = this.toJson();
-    await writeFile(jsonPath, await formatCode(JSON.stringify(json), "json", jsonPath));
+    await writeFile(jsonPath, await formatCode(JSON.stringify(json), jsonPath));
 
     // reload
     await EntityManager.register(json);

package/src/index.ts

@@ -31,6 +31,12 @@ export * from "./migration/types";
 export * from "./naite/naite";
 export * from "./naite/naite-reporter";
 export * from "./stream/sse";
+export * from "./stream/ws-audience";
+export * from "./stream/ws-cluster-bus";
+export * from "./stream/ws-core";
+export * from "./stream/ws-presence-store";
+export * from "./stream/ws";
+export * from "./stream/ws-registry";
 export * from "./tasks/decorator";
 export * from "./template/template";
 export * from "./template/template-manager";

package/src/migration/code-generation.ts

@@ -774,7 +774,7 @@ async function generateCreateCode_ColumnAndIndexes(
     table,
     type: "normal",
     title: `create__${table}`,
-    formatted: await formatCode(lines.join("\n"), "typescript", `src/migration/${table}.ts`),
+    formatted: await formatCode(lines.join("\n"), `src/migration/${table}.ts`),
   };
 }
 
@@ -871,12 +871,7 @@ function genNormalColumnDefinition(column: MigrationColumn): string {
     chains.push(`jsonb('${column.name}')`);
   } else {
     // type, length
-    let extraType: string | undefined;
-    chains.push(
-      `${column.type}('${column.name}'${
-        column.length ? `, ${column.length}` : ""
-      }${extraType ? `, '${extraType}'` : ""})`,
-    );
+    chains.push(`${column.type}('${column.name}'${column.length ? `, ${column.length}` : ""})`);
   }
 
   // nullable
@@ -1099,7 +1094,7 @@ async function generateCreateCode_Foreign(
       table,
       type: "foreign",
       title: `foreign__${table}__${foreignKeysString}`,
-      formatted: await formatCode(lines.join("\n"), "typescript", `src/migration/${table}.ts`),
+      formatted: await formatCode(lines.join("\n"), `src/migration/${table}.ts`),
     },
   ];
 }
@@ -1314,7 +1309,7 @@ async function generateAlterCode_ColumnAndIndexes(
     "}",
   ];
 
-  const formatted = await formatCode(lines.join("\n"), "typescript", `src/migration/${table}.ts`);
+  const formatted = await formatCode(lines.join("\n"), `src/migration/${table}.ts`);
   const title = [
     "alter",
     table,
@@ -1759,7 +1754,7 @@ async function generateAlterCode_Foreigns(
     "}",
   ];
 
-  const formatted = await formatCode(lines.join("\n"), "typescript", `src/migration/${table}.ts`);
+  const formatted = await formatCode(lines.join("\n"), `src/migration/${table}.ts`);
   const title = ["alter", table, "foreigns"].join("_");
 
   return [
@@ -2077,7 +2072,7 @@ async function generatePkTypeChangeMigration(
     "}",
   ];
 
-  const formatted = await formatCode(lines.join("\n"), "typescript", `src/migration/${table}.ts`);
+  const formatted = await formatCode(lines.join("\n"), `src/migration/${table}.ts`);
 
   return [
     {

package/src/shared/app.shared.ts.txt

@@ -12,9 +12,10 @@
 import type { AxiosRequestConfig } from "axios";
 import axios from "axios";
 import qs from "qs";
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { Alert } from "react-native";
 import { type core, z } from "zod";
+import { type InfiniteData } from "@tanstack/react-query";
 import { getCurrentLocale } from "@/i18n/sd.generated";
 import { ExpoEventSource as EventSource } from "@falcondev-oss/expo-event-source-polyfill";
 
@@ -358,8 +359,24 @@ export type SSEStreamState = {
   retryCount: number;
   isEnded: boolean;
 };
+export type WebSocketChannelOptions = {
+  enabled?: boolean;
+  retry?: number;
+  retryInterval?: number;
+  protocols?: string | string[];
+  headers?: Record<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>>(
@@ -510,7 +527,7 @@ export function useSSEStream<T extends Record<string, any>>(
             }
 
             try {
-              const data = JSON.parse(event.data as string);
+              const data = JSON.parse(event.data as string, dateReviver);
               handler(data);
             } catch (error) {
               console.error(`Failed to parse SSE data for event ${eventType}:`, error);
@@ -531,7 +548,7 @@ export function useSSEStream<T extends Record<string, any>>(
         }
 
         try {
-          const data = JSON.parse(event.data as string);
+          const data = JSON.parse(event.data as string, dateReviver);
           // 'message' 핸들러가 있으면 호출
           const messageHandler = handlersRef.current["message" as keyof T];
           if (messageHandler) {
@@ -580,7 +597,298 @@ 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, headers } = 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 !== 1) {
+      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 queryString = qs.stringify(params);
+    // 앱 shared는 Node/Native 실행도 염두에 두므로 baseURL과 추가 headers를 함께 반영함
+    const baseUrl = axios.defaults.baseURL ?? "$[[baseUrl]]";
+    const wsBaseUrl = baseUrl.replace(/^http:/, "ws:").replace(/^https:/, "wss:");
+    const fullUrl = new URL(queryString ? `${url}?${queryString}` : url, wsBaseUrl).toString();
+    const socket = new WebSocket(fullUrl, protocols, {
+      headers: {
+        "Accept-Language": getCurrentLocale(),
+        ...(headers ?? {}),
+      },
+    });
+    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 as string, 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), JSON.stringify(headers)]);
+
+  return {
+    ...state,
+    send,
+    close,
+  };
+}
+
+function isRetryableWebSocketCloseCode(code: number): boolean {
+  if (code === 1000) {
+    return false;
+  }
+
+  return ![1002, 1003, 1007, 1008, 1009].includes(code);
+}
+
 /*
   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 };
+}