sonamu 0.9.4 → 0.9.6

package/src/syncer/watcher.ts

@@ -0,0 +1,128 @@
+import { strict as assert } from "assert";
+import { type Stats } from "node:fs";
+import path from "path";
+
+import chalk from "chalk";
+import chokidar, { type FSWatcher } from "chokidar";
+import { minimatch } from "minimatch";
+
+import { Sonamu } from "../api";
+import { type AbsolutePath } from "../utils/path-utils";
+import { createFileEventBatcher } from "./event-batcher";
+import { getChecksumPatternGroupInAbsolutePath } from "./file-patterns";
+import { isLastChangedByMe } from "./file-tracking";
+
+/**
+ * Watcher를 설정합니다.
+ * 이 친구는 진짜로 syncer가 받아야 할 변경 이벤트들만 추려서 batch로 전달해줍니다.
+ */
+export async function setupWatcher(
+  onFileEvents: (fileEvents: Map<AbsolutePath, "change" | "add">) => Promise<void>,
+): Promise<FSWatcher> {
+  // api 본인뿐 아니라 sync target들의 src도 봅니다.
+  // target 산출물(sonamu.generated, services.generated, i18n copy 등)이 외부에서
+  // 변경되는 경우를 drift로 잡아 워닝을 띄우기 위함입니다.
+  const watcher = chokidar.watch(apiAndTargetsSrcPaths(), {
+    ignored: ignoreIfExtensionIsNotOneOf(".ts", ".json", ".http"),
+    persistent: true,
+    ignoreInitial: true,
+  });
+
+  // 100ms 안에 들어온 변경들을 한 batch로 모아 한 사이클로 처리합니다.
+  const pushFileEvent = createFileEventBatcher<"change" | "add">({
+    delayMs: 100,
+    onFlush: async (fileEvents) => {
+      const realChanges = new Map<AbsolutePath, "change" | "add">();
+      for (const [p, e] of fileEvents) {
+        // self-write echo는 flush 시점에 거릅니다.
+        // watcher.on에서 즉시 거르면 너무 이릅니다.
+        // 여기에서는 파일이 디스크에 쓰이고 나서 약간의 딜레이가 있기 때문에
+        // "디스크에 썼지만 아직 trackWritten이 완료되기 전 상태" 같은 문제가 사라집니다.
+        if (!(await isLastChangedByMe(p))) {
+          realChanges.set(p, e);
+        }
+      }
+      if (realChanges.size > 0) {
+        await onFileEvents(realChanges);
+      }
+    },
+  });
+
+  watcher.on("all", (event: string, filePath: string) => {
+    const absolutePath = filePath as AbsolutePath;
+    assert(
+      absolutePath.startsWith(Sonamu.appRootPath),
+      "File path is not within the app root path",
+    );
+
+    if (!isWantedEvent(event)) {
+      return;
+    }
+
+    if (isConfigChange(absolutePath)) {
+      triggerSelfRestart(event, filePath);
+      return;
+    }
+
+    if (isOutOfScope(absolutePath)) {
+      return;
+    }
+
+    // 여기까지 왔다면 syncer가 진짜로 처리해야 할 변경사항이라고 보면 됩니다.
+    // 이 호출은 이벤트를 batcher에 쌓습니다.
+    // 이후 때가 되면 이렇게 쌓인 이벤트를 들고 onFileEvents 콜백이 호출됩니다.
+    pushFileEvent(absolutePath, event);
+  });
+
+  return watcher;
+}
+
+function apiAndTargetsSrcPaths() {
+  return [
+    path.join(Sonamu.apiRootPath, "src"),
+    ...Sonamu.config.sync.targets.map((t) => path.join(Sonamu.appRootPath, t, "src")),
+  ];
+}
+
+/**
+ * chokidar의 `ignored` 옵션에 박는 헬퍼.
+ * 주어진 확장자가 *아닌* 파일은 무시합니다 — 즉 주어진 확장자만 watch 대상.
+ *
+ * chokidar `ignored`는 `true`를 반환하면 해당 경로를 무시합니다.
+ * 따라서 "이 확장자만 허용"을 표현하려면 *다른 확장자에 대해 true*를 반환해야 합니다.
+ */
+function ignoreIfExtensionIsNotOneOf(...allowedExtensions: `.${string}`[]) {
+  const isAllowed = (ext: string) => (allowedExtensions as string[]).includes(ext);
+
+  return (p: string, stats?: Stats) => !!stats?.isFile() && !isAllowed(path.extname(p));
+}
+
+function isWantedEvent(event: string): event is "change" | "add" {
+  return event === "change" || event === "add";
+}
+
+function isConfigChange(filePath: AbsolutePath): boolean {
+  return filePath === path.join(Sonamu.apiRootPath, "src", "sonamu.config.ts");
+}
+
+function triggerSelfRestart(event: string, filePath: string): void {
+  const relativePath = filePath.replace(Sonamu.apiRootPath, "api");
+  console.log(chalk.bold(`Detected(${event}): ${chalk.blue(relativePath)} - Restarting...`));
+  process.kill(process.pid, "SIGUSR2");
+}
+
+/**
+ * 스코프 정의:
+ * - api/src 안의 모든 변경은 스코프 안 (HMR 대상이 될 수 있으므로)
+ * - api/src 밖이라면 checksumPatternGroup 패턴에 매칭되는 경로만 스코프 안
+ *
+ * 그 외(예: web/src/App.tsx 같은 target의 비추적 파일)는 스코프 밖이라 무시합니다.
+ */
+function isOutOfScope(filePath: AbsolutePath): boolean {
+  const apiSrc = path.join(Sonamu.apiRootPath, "src");
+  if (filePath.startsWith(apiSrc)) {
+    return false;
+  }
+  const checkPatternGroup = getChecksumPatternGroupInAbsolutePath();
+  return !Object.values(checkPatternGroup).some((pattern) => minimatch(filePath, pattern));
+}

package/src/tasks/workflow-manager.ts

@@ -288,6 +288,7 @@ export class WorkflowManager {
       }>,
     ) => {
       const baseContext = {
+        transport: "http" as const,
         request: null,
         reply: null,
         headers: {},

package/src/template/__tests__/services.template.websocket.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { Sonamu } from "../../api";
+import { type ExtendedApi } from "../../api/decorators";
+import { EntityManager } from "../../entity/entity-manager";
+import { Template__services } from "../implementations/services.template";
+
+describe("Template__services websocket event refs", () => {
+  let originalConfig: unknown;
+  let originalSyncer: unknown;
+
+  beforeEach(() => {
+    originalConfig = Reflect.get(Sonamu, "_config");
+    originalSyncer = Reflect.get(Sonamu, "_syncer");
+  });
+
+  afterEach(() => {
+    Reflect.set(Sonamu, "_config", originalConfig);
+    Reflect.set(Sonamu, "_syncer", originalSyncer);
+  });
+
+  it("reuses websocket event type names when they are importable", () => {
+    Reflect.set(Sonamu, "_config", {
+      api: {
+        route: {
+          prefix: "/api",
+        },
+      },
+    });
+
+    const apis: ExtendedApi[] = [
+      {
+        modelName: "ChatFrame",
+        methodName: "subscribeChat",
+        path: "/chat/subscribeChat",
+        options: {
+          httpMethod: "GET",
+        },
+        websocketOptions: {
+          outEvents: z.object({
+            ready: z.object({
+              ok: z.boolean(),
+            }),
+          }),
+          inEvents: z.object({
+            ping: z.object({
+              at: z.string(),
+            }),
+          }),
+          outEventsTypeRef: {
+            t: "ref",
+            id: "ChatOutEvents",
+          },
+          inEventsTypeRef: {
+            t: "ref",
+            id: "ChatInEvents",
+          },
+        },
+        typeParameters: [],
+        parameters: [],
+        returnType: "void",
+      },
+    ];
+    Reflect.set(Sonamu, "_syncer", {
+      apis,
+    });
+
+    EntityManager.setModulePath("ChatOutEvents", "chat/chat.types");
+    EntityManager.setModulePath("ChatInEvents", "chat/chat.types");
+
+    const template = new Template__services();
+    const rendered = template.render({});
+
+    expect(rendered.body).toContain("handlers: EventHandlers<ChatOutEvents>");
+    expect(rendered.body).toContain("useWebSocketChannel<ChatOutEvents, ChatInEvents>");
+    expect(rendered.importKeys).toEqual(expect.arrayContaining(["ChatOutEvents", "ChatInEvents"]));
+  });
+});

package/src/template/implementations/services.template.ts

@@ -43,6 +43,27 @@ export class Template__services extends Template {
     const importKeys: string[] = [];
     const namespaces: string[] = [];
     let typeParamNames: string[] = [];
+    const resolveWebSocketEventTypeDef = (
+      typeRef: ApiParamType.Ref | undefined,
+      schema: Parameters<typeof zodTypeToTsTypeDef>[0],
+    ): string => {
+      if (typeRef) {
+        const candidateImportKeys: string[] = [];
+        const candidateTypeDef = apiParamTypeToTsType(typeRef, candidateImportKeys);
+
+        try {
+          for (const key of unique(candidateImportKeys)) {
+            EntityManager.getModulePath(key);
+          }
+          importKeys.push(...candidateImportKeys);
+          return candidateTypeDef;
+        } catch {
+          // 로컬 const 등 import 가능한 심볼이 아니면 기존 inline 생성으로 후퇴
+        }
+      }
+
+      return zodTypeToTsTypeDef(schema);
+    };
 
     for (const [modelName, modelApis] of apisByModel) {
       const functions: string[] = [];
@@ -86,6 +107,52 @@ export function ${methodNameStreamCamelized}(
           continue;
         }
 
+        if (api.websocketOptions) {
+          // websocket surface는 fetch 함수 대신 typed hook을 생성함
+          const paramsWithoutContext = api.parameters.filter(
+            (param) =>
+              !ApiParamType.isContext(param.type) &&
+              !ApiParamType.isRefKnex(param.type) &&
+              !(param.optional && param.name.startsWith("_")),
+          );
+
+          const apiBaseUrl = `${Sonamu.config.api.route.prefix}${api.path}`;
+
+          const methodNameWebSocket = api.options.resourceName
+            ? `use${inflection.camelize(api.options.resourceName)}`
+            : `use${inflection.camelize(api.methodName)}`;
+          const methodNameWebSocketCamelized = inflection.camelize(methodNameWebSocket, true);
+
+          // outEvents는 수신 타입, inEvents는 send() 입력 타입으로 사용함
+          const outEventsTypeDef = resolveWebSocketEventTypeDef(
+            api.websocketOptions.outEventsTypeRef,
+            api.websocketOptions.outEvents,
+          );
+          const inEventsTypeDef = resolveWebSocketEventTypeDef(
+            api.websocketOptions.inEventsTypeRef,
+            api.websocketOptions.inEvents,
+          );
+
+          // context/refKnex/internal optional 파라미터는 클라이언트 입력에서 제외함
+          const paramsDefAsObject =
+            paramsWithoutContext.length > 0
+              ? `{ ${paramsWithoutContext.map((p) => `${p.name}: ${apiParamTypeToTsType(p.type, importKeys)}`).join(", ")} }`
+              : "{}";
+
+          functions.push(
+            `
+export function ${methodNameWebSocketCamelized}(
+  params: ${paramsDefAsObject},
+  handlers: EventHandlers<${outEventsTypeDef}>,
+  options: WebSocketChannelOptions = {}
+) {
+  return useWebSocketChannel<${outEventsTypeDef}, ${inEventsTypeDef}>(\`${apiBaseUrl}\`, params, handlers, options);
+}
+            `.trim(),
+          );
+          continue;
+        }
+
         // Context 제외한 파라미터
         const paramsWithoutContext = api.parameters.filter(
           (param) =>
@@ -397,7 +464,9 @@ export const ${names.capital}AsyncIdConfig: AsyncIdConfig<${names.capital}Subset
       "fetch",
       "type EventHandlers",
       "type SSEStreamOptions",
+      "type WebSocketChannelOptions",
       "useSSEStream",
+      "useWebSocketChannel",
       "toFormData",
       ...(needsDedupeAndFlatten ? ["dedupeAndFlatten"] : []),
       ...(needsUseRefreshable ? ["useRefreshable"] : []),

package/src/testing/bootstrap.ts

@@ -58,11 +58,18 @@ export function bootstrap(vi: VitestUtils, options?: BootstrapOptions) {
 
 function getMockContext(): Context {
   return {
+    transport: "http",
+    request: null as unknown as Context["request"],
+    reply: null as unknown as Context["reply"],
+    headers: {},
+    createSSE: (() => {
+      throw new Error("createSSE is not available in mock context");
+    }) as Context["createSSE"],
     session: null,
     user: null,
     naiteStore: Naite.createStore(),
     locale: "",
-  } as unknown as Context;
+  };
 }
 
 export async function runWithContext(context: Context | null, fn: () => Promise<void>) {

package/src/testing/data-explorer.ts

@@ -4,6 +4,7 @@ import { type CacheManager } from "../cache/types";
 import { type Entity } from "../entity/entity";
 import { type EntityManager } from "../entity/entity-manager";
 import { isBelongsToOneRelationProp, isOneToOneRelationProp, isRelationProp } from "../types/types";
+import { nonNullable } from "../utils/utils";
 
 export type DataExplorerStrategy = "sample" | "ids" | "query" | "file" | "recent" | "random";
 
@@ -323,7 +324,7 @@ export class DataExplorer {
     }
 
     const entity = this.entityManager.get(entityName);
-    const recordIds = records.map((r) => r.id).filter((id) => id != null);
+    const recordIds = records.map((r) => r.id).filter(nonNullable);
 
     // 1. Forward references: 이 entity가 참조하는 다른 entity
     const forwardRelationProps = entity.props.filter(
@@ -346,7 +347,7 @@ export class DataExplorer {
       const foreignKeyName = `${prop.name}_id`;
       const referencedIds = records
         .map((record) => record[foreignKeyName])
-        .filter((id) => id != null) as number[];
+        .filter(Boolean) as number[];
 
       if (referencedIds.length === 0) {
         continue;

package/src/types/types.ts

@@ -992,7 +992,8 @@ export namespace ApiParamType {
       typeof v === "object" &&
       v !== null &&
       (v as { t?: unknown }).t === "ref" &&
-      (v as { id?: unknown }).id === "Context"
+      ((v as { id?: unknown }).id === "Context" ||
+        (v as { id?: unknown }).id === "WebSocketContext")
     );
   }
   export function isRefKnex(v: unknown): v is ApiParamType.Ref {
@@ -1774,11 +1775,28 @@ export type SonamuFastifyConfig = {
   contextProvider: (
     defaultContext: Pick<
       Context,
-      "request" | "reply" | "headers" | "createSSE" | "naiteStore" | "locale" | "user" | "session"
+      | "transport"
+      | "request"
+      | "reply"
+      | "headers"
+      | "createSSE"
+      | "naiteStore"
+      | "locale"
+      | "user"
+      | "session"
     >,
     request: FastifyRequest,
     reply: FastifyReply,
   ) => Context | Promise<Context>;
+  websocketContextProvider?: (
+    defaultContext: Pick<
+      import("../api/context").WebSocketContext,
+      "transport" | "request" | "headers" | "ws" | "naiteStore" | "locale" | "user" | "session"
+    >,
+    request: FastifyRequest,
+  ) =>
+    | import("../api/context").WebSocketContext
+    | Promise<import("../api/context").WebSocketContext>;
   guardHandler: (
     guard: GuardKey,
     request: FastifyRequest,

package/src/ui/api.ts

@@ -256,8 +256,17 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             const entity = EntityManager.get(entityId);
             const subsetRows = entity.getSubsetRows();
 
+            // zod 인스턴스를 spread하면 JSON.stringify가 reference를 인라인으로 풀어내며 응답이 수백 MB까지 부풀어 V8 string limit를 초과한다.
+            const {
+              types: _types,
+              enums: _enums,
+              enumCones: _enumCones,
+              subsetCones: _subsetCones,
+              ...rest
+            } = entity;
+
             return {
-              ...entity,
+              ...rest,
               flattenSubsetRows: flattenSubsetRows(subsetRows),
             };
           }),

package/src/utils/async-utils.ts

@@ -1,6 +1,9 @@
 import { glob } from "fs/promises";
 import path from "path";
 
+import { minimatch } from "minimatch";
+import { debounce } from "radashi";
+
 /**
  * 비동기 조건으로 배열을 필터링합니다
  * @example
@@ -65,13 +68,77 @@ export async function reduceAsync<T, U>(
 /**
  * 비동기 glob 함수입니다.
  * AsyncIterableIterator로 날아오는 glob의 반환을 받아 끝까지 돌아서 배열로 반환합니다.
- * @param pathPattern
- * @returns
+ *
+ * @param pathPattern glob 패턴 (절대 경로 또는 상대 경로)
+ * @param options.exclude 매치에서 제외할 패턴 목록 (예: `["**\/node_modules/**"]`).
+ *   alternation을 포함하는 패턴이 의도치 않게 빌드 산출물 디렉토리를 휘말리게 하는 것을 막는 안전망.
  */
-export async function globAsync(pathPattern: string): Promise<string[]> {
+export async function globAsync(
+  pathPattern: string,
+  options?: { exclude?: string[] },
+): Promise<string[]> {
   const files: string[] = [];
-  for await (const file of glob(path.resolve(pathPattern))) {
+  const excludePatterns = options?.exclude;
+  const iter = excludePatterns
+    ? glob(path.resolve(pathPattern), {
+        exclude: (filePath: string) =>
+          excludePatterns.some((pat) => minimatch(filePath, pat, { dot: true })),
+      })
+    : glob(path.resolve(pathPattern));
+  for await (const file of iter) {
     files.push(file);
   }
   return files;
 }
+
+/**
+ * 키별로 trailing-edge debounce. 같은 key에 대해 delay 안에 여러 번 호출되면 마지막 args만
+ * delay 후에 fn 호출. key가 다르면 timer 독립적.
+ *
+ * @example
+ * const debounced = debounceByKey<string>(100, (path) => handleFileChange(path));
+ * debounced("a.ts"); debounced("a.ts"); // 100ms 후 한 번만 호출
+ * debounced("b.ts"); // a.ts와 별개로 100ms 후 호출
+ */
+export function debounceByKey<K, A extends unknown[]>(
+  delay: number,
+  fn: (key: K, ...args: A) => void | Promise<void>,
+): (key: K, ...args: A) => void {
+  const debouncersByKey = new Map<K, (key: K, ...args: A) => void>();
+  return (key, ...args) => {
+    let debounced = debouncersByKey.get(key);
+    if (!debounced) {
+      debounced = debounce({ delay }, (k: K, ...a: A) => {
+        void fn(k, ...a);
+      });
+      debouncersByKey.set(key, debounced);
+    }
+    debounced(key, ...args);
+  };
+}
+
+/**
+ * 같은 key에 대한 호출 결과를 캐시. 같은 key로 다시 호출되면 fn 실행 없이 캐시값 반환.
+ * 무효화는 프로세스 재시작 (또는 외부에서 invalidate). 호출자가 keyFn으로 args → string 매핑.
+ *
+ * @example
+ * const cachedFmt = cached(formatCodeInternal, (code, filePath) => `${ext(filePath)}:${sha1(code)}`);
+ * await cachedFmt(code, "a.ts"); // 실제 호출
+ * await cachedFmt(code, "a.ts"); // 캐시 hit
+ */
+export function cached<A extends unknown[], R>(
+  fn: (...args: A) => Promise<R>,
+  keyFn: (...args: A) => string,
+): (...args: A) => Promise<R> {
+  const cache = new Map<string, R>();
+  return async (...args) => {
+    const key = keyFn(...args);
+    const hit = cache.get(key);
+    if (hit !== undefined) {
+      return hit;
+    }
+    const result = await fn(...args);
+    cache.set(key, result);
+    return result;
+  };
+}