sonamu 0.10.12 → 0.10.13

package/src/naite/naite.ts

@@ -1,5 +1,3 @@
-/* oxlint-disable @typescript-eslint/no-explicit-any */ // Naite는 expect와 호응하도록 any를 허용함
-
 import { getLogger } from "@logtape/logtape";
 import { get } from "radashi";
 
@@ -7,6 +5,7 @@ import { Sonamu } from "../api/sonamu";
 import { type ComparisonOperator } from "../database/puri.types";
 import { convertNaiteKeyToCategory } from "../logger/category";
 import { isSerializable } from "../utils/object-utils";
+import { isNumberValue, isStringValue } from "../utils/runtime-value";
 
 // StackFrame 타입
 interface StackFrame {
@@ -18,11 +17,78 @@ interface StackFrame {
 // NaiteTrace 타입
 interface NaiteTrace {
   key: string;
-  data: any;
+  data: NaiteData;
   stack: StackFrame[]; // 콜스택 정보
   at: Date;
 }
 
+// Naite는 직렬화 가능성 검사를 내보내기 시점에 수행하므로 모든 JavaScript 값을 기록할 수 있습니다.
+export type NaiteData = null | undefined | bigint | boolean | number | object | string | symbol;
+
+export interface NaiteEventRegistry {
+  actionGenerateServices: readonly object[];
+  "fs/promises:rm": {
+    path: string;
+    options?: object;
+  };
+  "fs/promises:writeFile": {
+    path: string;
+    data: string;
+  };
+  "puri:executed-query": string;
+  "puri:ub-batch-updated": {
+    tableName: string;
+    rowCount: number;
+    whereColumns: string[];
+  };
+  "puri:ub-clean-orphans": {
+    tableName: string;
+    cleanOrphans: string[];
+    deletedCount: number;
+  };
+  "puri:ub-inherit": {
+    tableName: string;
+    inheritColumns: string[];
+    excludedFromUpdate: string[];
+  };
+  "puri:ub-ref-resolved": {
+    tableName: string;
+    field: string;
+    from: UBReference;
+    to: NaiteData;
+  };
+  "puri:ub-register": {
+    tableName: string;
+    uuid: string;
+    isUuidReused: boolean;
+    row: object & { user_id: UBReference };
+  };
+  "puri:ub-upserted": {
+    tableName: string;
+    mode: "insert" | "upsert";
+    rowCount: number;
+    returnedIds: Array<number | string>;
+  };
+}
+
+interface UBReference {
+  uuid: string;
+  of: string;
+  use?: string;
+}
+
+export interface NaiteResult<Payload> extends Array<Payload> {
+  0: Payload;
+  1: Payload;
+  [index: number]: Payload;
+  find<Match extends Payload>(
+    predicate: (value: Payload, index: number, values: Payload[]) => value is Match,
+  ): Match;
+  find(predicate: (value: Payload, index: number, values: Payload[]) => boolean): Payload;
+}
+
+type NaiteValuesByKey = Record<string, NaiteTrace[] | Array<NaiteTrace["data"]>>;
+
 // Naite.t가 저장되는 타입 (항상 배열로 통일)
 export type NaiteStore = Map<string, NaiteTrace[]>;
 
@@ -30,7 +96,7 @@ export type NaiteStore = Map<string, NaiteTrace[]>;
 // bootstrap.ts의 TaskMeta augmentation, dev-vitest-manager.ts에서도 이 타입을 공유합니다.
 export type SerializedTrace = {
   key: string;
-  value: any;
+  value: unknown;
   filePath: string;
   lineNumber: number;
   at: string;
@@ -140,22 +206,22 @@ function matchesPattern(key: string, pattern: string): boolean {
  * NaiteQuery 클래스
  * 체이닝을 통한 trace 필터링 및 조회
  */
-export class NaiteQuery {
+export class NaiteQuery<Payload extends NaiteData = NaiteData> {
   constructor(private traces: NaiteTrace[]) {}
 
-  private isComparableValue(value: unknown): value is number | string {
-    return typeof value === "number" || typeof value === "string";
+  private isComparableValue<Value>(value: Value): value is Value & (number | string) {
+    return isNumberValue(value) || isStringValue(value);
   }
 
   /**
    * 파일명으로 필터링
    * @param fileName 파일명 (예: "syncer.test.ts")
    */
-  fromFile(fileName: string): NaiteQuery {
+  fromFile(fileName: string): NaiteQuery<Payload> {
     const filtered = this.traces.filter((t) =>
       t.stack.some((frame) => frame.filePath.endsWith(`/${fileName}`)),
     );
-    return new NaiteQuery(filtered);
+    return new NaiteQuery<Payload>(filtered);
   }
 
   /**
@@ -166,7 +232,7 @@ export class NaiteQuery {
   fromFunction(
     funcName: string,
     options: { from: "direct" | "indirect" | "both" } = { from: "both" },
-  ): NaiteQuery {
+  ): NaiteQuery<Payload> {
     const filtered = this.traces.filter((t) => {
       if (options.from === "direct") {
         // stack[0]만 확인 (직접 호출)
@@ -179,7 +245,7 @@ export class NaiteQuery {
       // 전체 스택에서 확인
       return t.stack.some((f) => f.functionName?.includes(funcName));
     });
-    return new NaiteQuery(filtered);
+    return new NaiteQuery<Payload>(filtered);
   }
 
   /**
@@ -188,7 +254,11 @@ export class NaiteQuery {
    * @param operator 비교 연산자
    * @param value 비교값
    */
-  where(path: string, operator: ComparisonOperator | "includes", value: any): NaiteQuery {
+  where<Value extends NaiteData>(
+    path: string,
+    operator: ComparisonOperator | "includes",
+    value: Value,
+  ): NaiteQuery<Payload> {
     const filtered = this.traces.filter((trace) => {
       const actual = get(trace, path);
 
@@ -206,39 +276,43 @@ export class NaiteQuery {
         case "!=":
           return actual !== value;
         case "includes":
-          return typeof actual === "string" && actual.includes(value);
+          return isStringValue(actual) && isStringValue(value) && actual.includes(value);
         default:
           return false;
       }
     });
-    return new NaiteQuery(filtered);
+    return new NaiteQuery<Payload>(filtered);
   }
 
   /**
    * 전체 데이터 배열 반환
    */
-  result(): any[] {
+  result(): NaiteResult<Payload>;
+  result(): NaiteData[] {
     return this.traces.map((t) => t.data);
   }
 
   /**
    * 첫 번째 데이터 반환
    */
-  first(): any | undefined {
+  first(): Payload;
+  first(): NaiteData {
     return this.traces[0]?.data;
   }
 
   /**
    * 마지막 데이터 반환
    */
-  last(): any | undefined {
+  last(): Payload;
+  last(): NaiteData {
     return this.traces[this.traces.length - 1]?.data;
   }
 
   /**
    * n번째 데이터 반환
    */
-  at(index: number): any | undefined {
+  at(index: number): Payload;
+  at(index: number): NaiteData {
     return this.traces[index]?.data;
   }
 
@@ -253,10 +327,7 @@ export class NaiteQuery {
 // Naite 싱글턴 객체 (추후 logger 연결 등의 상태 관리 필요성 고려)
 export class NaiteClass {
   // 테스트 로그 기록
-  t(
-    name: string,
-    value: any /*이렇게 받은 값이 NaiteTrace로 저장되어 있다가 추후에 vitest에게 meta를 통해 넘겨져 프로세스간 통신을 통해 직렬화되어야 하는 점을 고려하였을 때 여기에 Serializable을 써서 제한을 둘 수도 있지만, 사용상의 편의를 생각하여 any로 받습니다.*/,
-  ) {
+  t<Value extends NaiteData>(name: string, value: Value) {
     // 이 t 함수는 테스트 환경에서만 작동해야 합니다.
     // 그리고 테스트 환경 판단에 왜 isTest() 함수를 사용하지 않았냐면요,,
     // 이렇게 하는게 유틸 함수 불러와서 사용하는 것보다 조금이나마 빠를 것 같았기 때문입니다.
@@ -302,6 +373,8 @@ export class NaiteClass {
    * key 또는 wildcard 패턴으로 trace 조회
    * 항상 NaiteQuery 반환하여 체이닝 가능
    */
+  get<Key extends keyof NaiteEventRegistry>(keyPattern: Key): NaiteQuery<NaiteEventRegistry[Key]>;
+  get(keyPattern: string): NaiteQuery;
   get(keyPattern: string): NaiteQuery {
     const context = Sonamu.getContext();
     const store = context?.naiteStore;
@@ -328,13 +401,13 @@ export class NaiteClass {
   }
 
   // 전체 리스트 가져오기
-  getAll(): { [key: string]: any } {
+  getAll() {
     const context = Sonamu.getContext();
     if (!context?.naiteStore) {
       return {};
     }
     // NaiteTrace 배열을 data만 추출하여 반환
-    const result: { [key: string]: any } = {};
+    const result: NaiteValuesByKey = {};
     for (const [key, traces] of context.naiteStore.entries()) {
       if (key.startsWith("mock:")) {
         // Mock 설정은 그대로 반환

package/src/runtime-type.ts

@@ -0,0 +1,34 @@
+import {
+  isBigIntValue,
+  isFunctionValue,
+  isNumberValue,
+  isStringValue,
+  isSymbolValue,
+} from "./utils/runtime-value";
+
+export type RuntimeType =
+  | "bigint"
+  | "boolean"
+  | "function"
+  | "number"
+  | "object"
+  | "string"
+  | "symbol"
+  | "undefined";
+
+/** 런타임 값이 불리언인지 판별합니다. */
+export function isBooleanValue<Value>(value: Value): value is Value & boolean {
+  return value === true || value === false;
+}
+
+/** JavaScript의 typeof 결과를 단항 연산자 없이 동일하게 계산합니다. */
+export function runtimeTypeOf<Value>(value: Value): RuntimeType {
+  if (value === undefined) return "undefined";
+  if (isStringValue(value)) return "string";
+  if (isNumberValue(value)) return "number";
+  if (isBooleanValue(value)) return "boolean";
+  if (isBigIntValue(value)) return "bigint";
+  if (isSymbolValue(value)) return "symbol";
+  if (isFunctionValue(value)) return "function";
+  return "object";
+}

package/src/ssr/hmr-opt-out.ts

@@ -0,0 +1,78 @@
+/**
+ * 페이지 단위 HMR 비활성화(`?hmr=false`).
+ *
+ * 에이전트가 코드를 고치는 동안 사람이 보고 있는 탭이 계속 새로고침되는 것을 막기 위해,
+ * 해당 URL로 연 페이지에서만 Vite HMR을 끊는다.
+ *
+ * Vite는 페이지 단위 HMR 토글을 제공하지 않는다. `server.hmr: false`는 서버 전체에 적용되고,
+ * HTML에서 `/@vite/client` 스크립트 태그만 제거하는 방식도 통하지 않는다.
+ * 변환된 모듈마다 `import { createHotContext } from "/@vite/client"`가 들어가기 때문이다.
+ *
+ * 그래서 HMR 웹소켓 자체를 막는다. Vite HMR 소켓은 서브프로토콜로 구분되므로
+ * (`vite-hmr`, 재연결 확인은 `vite-ping`), 앱이 같은 포트에서 쓰는 웹소켓
+ * (Sonamu telemetry, ctx.ws 등)은 그대로 두고 HMR만 골라낼 수 있다.
+ *
+ * 연결 실패로 처리하지 않고 "영원히 연결 중"인 더미 소켓을 돌려주는 이유는,
+ * Vite 클라이언트가 소켓이 닫히면 재연결을 폴링하다가 성공 시 `location.reload()`를
+ * 호출하기 때문이다. close/error 이벤트를 아예 발생시키지 않아야 새로고침되지 않는다.
+ */
+
+const HMR_OPT_OUT_QUERY = "hmr";
+
+/** 요청 URL에 `?hmr=false`가 있는지 확인한다. */
+export function isHmrDisabledByQuery(url: string): boolean {
+  const queryIndex = url.indexOf("?");
+  if (queryIndex === -1) {
+    return false;
+  }
+
+  const params = new URLSearchParams(url.slice(queryIndex + 1));
+  const value = params.get(HMR_OPT_OUT_QUERY);
+  return value === "false" || value === "0";
+}
+
+/**
+ * HMR 웹소켓만 무력화하는 인라인 스크립트.
+ * 모듈 스크립트(`type="module"`)는 지연 실행되므로, 이 classic 스크립트가 항상 먼저 실행된다.
+ */
+export const HMR_OPT_OUT_SCRIPT = `<script>
+(() => {
+  var NativeWebSocket = window.WebSocket;
+  if (!NativeWebSocket) return;
+  var HMR_PROTOCOLS = ["vite-hmr", "vite-ping"];
+
+  function createIdleSocket(url) {
+    // 열리지도 닫히지도 않는 더미. close/error를 발생시키면 Vite가 재연결 후 새로고침한다.
+    return {
+      url: String(url),
+      readyState: 0,
+      protocol: "",
+      bufferedAmount: 0,
+      extensions: "",
+      binaryType: "blob",
+      onopen: null, onclose: null, onerror: null, onmessage: null,
+      addEventListener: function () {},
+      removeEventListener: function () {},
+      dispatchEvent: function () { return false; },
+      send: function () {},
+      close: function () {},
+      CONNECTING: 0, OPEN: 1, CLOSING: 2, CLOSED: 3,
+    };
+  }
+
+  window.WebSocket = new Proxy(NativeWebSocket, {
+    construct: function (Target, args) {
+      var requested = args[1];
+      var protocols = Array.isArray(requested) ? requested : requested ? [requested] : [];
+      var isHmr = protocols.some(function (protocol) {
+        return HMR_PROTOCOLS.indexOf(protocol) !== -1;
+      });
+      if (isHmr) {
+        console.info("[sonamu] hmr=false: 이 페이지의 Vite HMR 연결을 막았습니다. 변경 사항은 반영되지 않습니다.");
+        return createIdleSocket(args[0]);
+      }
+      return new Target(...args);
+    },
+  });
+})();
+</script>`;

package/src/ssr/renderer.ts

@@ -6,6 +6,7 @@ import { type ViteDevServer } from "vite";
 import { applyCacheHeaders } from "../cache-control/cache-control";
 import { type CacheControlRequest } from "../cache-control/types";
 import { type SonamuFastifyConfig } from "../types/types";
+import { HMR_OPT_OUT_SCRIPT, isHmrDisabledByQuery } from "./hmr-opt-out";
 import { type PreloadedData, type SSRRoute } from "./types";
 
 export async function renderSSR(
@@ -61,6 +62,11 @@ export async function renderSSR(
     // Vite가 주입한 스크립트 추출
     viteScripts = extractScriptTags(transformedHtml);
 
+    // ?hmr=false로 연 페이지는 HMR 웹소켓만 끊어 새로고침되지 않게 한다.
+    if (isHmrDisabledByQuery(url)) {
+      viteScripts = `${HMR_OPT_OUT_SCRIPT}\n${viteScripts}`;
+    }
+
     const entryModule = await vite.ssrLoadModule("/src/entry-server.generated.tsx");
     render = entryModule.render;
   } else {

package/src/storage/base-file.ts

@@ -17,46 +17,46 @@ export abstract class BaseFile {
     url?: string;
     signedUrl?: string;
   }) {
-    this._filename = params.filename;
-    this._mimetype = params.mimetype;
-    this._size = params.size;
-    this._url = params.url;
-    this._signedUrl = params.signedUrl;
+    this["_filename"] = params.filename;
+    this["_mimetype"] = params.mimetype;
+    this["_size"] = params.size;
+    this["_url"] = params.url;
+    this["_signedUrl"] = params.signedUrl;
   }
 
   /** 원본 파일명 */
   get filename(): string {
-    return this._filename;
+    return this["_filename"];
   }
 
   /** MIME 타입 */
   get mimetype(): string {
-    return this._mimetype;
+    return this["_mimetype"];
   }
 
   /** 파일 크기 (bytes) */
   get size(): number {
-    return this._size;
+    return this["_size"];
   }
 
   /** 확장자 (점 제외) */
   get extname(): string | false {
-    return mime.extension(this._mimetype);
+    return mime.extension(this["_mimetype"]);
   }
 
   /** 저장된 URL (Unsigned) */
   get url(): string {
-    if (this._url === undefined) {
+    if (this["_url"] === undefined) {
       throw new Error("url이 설정되지 않았습니다.");
     }
-    return this._url;
+    return this["_url"];
   }
 
   /** 저장된 URL (Signed) */
   get signedUrl(): string {
-    if (this._signedUrl === undefined) {
+    if (this["_signedUrl"] === undefined) {
       throw new Error("signedUrl이 설정되지 않았습니다.");
     }
-    return this._signedUrl;
+    return this["_signedUrl"];
   }
 }

package/src/storage/buffered-file.ts

@@ -10,8 +10,8 @@ import { type DriverKey } from "./drivers";
  * 메모리에 로드된 상태로, md5 계산이나 이미지 처리 등 유연한 작업이 가능합니다.
  */
 export class BufferedFile extends BaseFile {
-  private _file: MultipartFile;
-  private _buffer: Buffer;
+  private fileValue: MultipartFile;
+  private bufferValue: Buffer;
 
   constructor(file: MultipartFile, buffer: Buffer) {
     super({
@@ -19,18 +19,18 @@ export class BufferedFile extends BaseFile {
       mimetype: file.mimetype,
       size: buffer.length,
     });
-    this._file = file;
-    this._buffer = buffer;
+    this.fileValue = file;
+    this.bufferValue = buffer;
   }
 
   /** 파일 Buffer */
   get buffer(): Buffer {
-    return this._buffer;
+    return this.bufferValue;
   }
 
   /** MD5 해시 계산 */
   async md5(): Promise<string> {
-    return createHash("md5").update(this._buffer).digest("hex");
+    return createHash("md5").update(this.bufferValue).digest("hex");
   }
 
   /**
@@ -44,19 +44,19 @@ export class BufferedFile extends BaseFile {
     const { Sonamu } = await import("../api/sonamu");
     const disk = Sonamu.storage.use(diskName);
 
-    await disk.put(key, new Uint8Array(this._buffer), {
+    await disk.put(key, new Uint8Array(this.bufferValue), {
       contentType: this.mimetype,
     });
 
-    this._url = await disk.getUrl(key);
-    this._signedUrl = await disk.getSignedUrl(key);
+    this["_url"] = await disk.getUrl(key);
+    this["_signedUrl"] = await disk.getSignedUrl(key);
 
     // signed url은 만료 시간이 있기 때문에, unsigned url을 반환합니다.
-    return this._url;
+    return this["_url"];
   }
 
   /** 원본 MultipartFile 접근 */
   get raw(): MultipartFile {
-    return this._file;
+    return this.fileValue;
   }
 }

package/src/storage/s3-driver.ts

@@ -62,7 +62,10 @@ export class SonamuS3Driver extends S3Driver {
 
     // ACL 지원 시에만 설정
     if (this.sonamuSupportsACL) {
-      uploadParams.ACL = (visibility === "public" ? "public-read" : "private") as ObjectCannedACL;
+      uploadParams.ACL =
+        /* SAFETY: 호출 경계의 선행 검증과 소유 타입 계약이 이 값의 타입을 보장한다. */ (
+          visibility === "public" ? "public-read" : "private"
+        ) as ObjectCannedACL;
     }
 
     const upload = new Upload({

package/src/storage/uploaded-file.ts

@@ -6,8 +6,8 @@ import { type DriverKey } from "./drivers";
  * 이미 저장소에 스트리밍 완료된 상태로, url/key 등 메타데이터만 접근 가능합니다.
  */
 export class UploadedFile extends BaseFile {
-  private _key: string;
-  private _diskName: DriverKey;
+  private keyValue: string;
+  private diskNameValue: DriverKey;
 
   constructor(params: {
     filename: string;
@@ -25,18 +25,18 @@ export class UploadedFile extends BaseFile {
       url: params.url,
       signedUrl: params.signedUrl,
     });
-    this._key = params.key;
-    this._diskName = params.diskName;
+    this.keyValue = params.key;
+    this.diskNameValue = params.diskName;
   }
 
   /** 저장소 내 키 */
   get key(): string {
-    return this._key;
+    return this.keyValue;
   }
 
   /** 저장된 디스크 이름 */
   get diskName(): DriverKey {
-    return this._diskName;
+    return this.diskNameValue;
   }
 
   /**
@@ -45,9 +45,9 @@ export class UploadedFile extends BaseFile {
    */
   async download(): Promise<Buffer> {
     const { Sonamu } = await import("../api/sonamu");
-    const disk = Sonamu.storage.use(this._diskName);
+    const disk = Sonamu.storage.use(this.diskNameValue);
 
-    const uint8Array = await disk.get(this._key);
+    const uint8Array = await disk.get(this.keyValue);
     return Buffer.from(uint8Array);
   }
 }

package/src/stream/__tests__/ws-contracts.test.ts

@@ -13,6 +13,8 @@ import { WebSocketDeliveryEngine } from "../ws-delivery";
 import { WebSocketLocalConnectionStore } from "../ws-local-connection-store";
 import { InMemoryWebSocketPresenceStore } from "../ws-presence-store";
 
+type PublishedData = Parameters<ManagedWebSocketConnection["publishUntyped"]>[1];
+
 async function waitForAsyncQueue(rounds: number = 3): Promise<void> {
   for (let index = 0; index < rounds; index += 1) {
     await new Promise<void>((resolve) => {
@@ -48,7 +50,7 @@ class ContractClusterBus implements WebSocketClusterBus {
 }
 
 class ContractConnection implements ManagedWebSocketConnection {
-  readonly sent: Array<{ event: string; data: unknown }> = [];
+  readonly sent: Array<{ event: string; data: PublishedData }> = [];
   closed = false;
 
   constructor(
@@ -56,7 +58,7 @@ class ContractConnection implements ManagedWebSocketConnection {
     readonly namespace: string,
   ) {}
 
-  publishUntyped(event: string, data: unknown): void {
+  publishUntyped<Data>(event: string, data: Data): void {
     this.sent.push({ event, data });
   }
 

package/src/stream/__tests__/ws-telemetry.test.ts

@@ -562,7 +562,7 @@ describe("metric source", () => {
     };
 
     const unsubscribe = controller.registerMetricSource(source);
-    expect(typeof unsubscribe).toBe("function");
+    expect(unsubscribe).toBeInstanceOf(Function);
 
     const snapshotBefore = controller.getMetricsSnapshot();
     expect(snapshotBefore.activeConnections).toBe(7);

package/src/stream/__tests__/ws.test.ts

@@ -1,10 +1,9 @@
 import { EventEmitter } from "node:events";
 
 import { describe, expect, it, vi } from "vitest";
-import { type WebSocket } from "ws";
 import { z } from "zod";
 
-import { createWebSocketRuntime } from "../ws";
+import { createWebSocketRuntime, type WebSocketTransport } from "../ws";
 import { WebSocketAudience } from "../ws-audience";
 import {
   type WebSocketClusterBus,
@@ -48,8 +47,33 @@ class FakeWebSocket extends EventEmitter {
   }
 }
 
-function asWebSocket(socket: FakeWebSocket): WebSocket {
-  return socket as unknown as WebSocket;
+function asWebSocket(socket: FakeWebSocket): WebSocketTransport {
+  return {
+    get bufferedAmount() {
+      return socket.bufferedAmount;
+    },
+    get readyState() {
+      return socket.readyState;
+    },
+    close(code, reason) {
+      socket.close(code, reason?.toString());
+    },
+    off(...args) {
+      socket.off(...args);
+    },
+    on(...args) {
+      socket.on(...args);
+    },
+    ping() {
+      socket.ping();
+    },
+    send(data) {
+      socket.send(data.toString());
+    },
+    terminate() {
+      socket.terminate();
+    },
+  };
 }
 
 class FakeClusterBus implements WebSocketClusterBus {
@@ -665,8 +689,8 @@ describe("WebSocketRuntime", () => {
       namespace: "chat",
     });
 
-    let unhandled: unknown = null;
-    const handleUnhandledRejection = (reason: unknown) => {
+    let unhandled: Error | null = null;
+    const handleUnhandledRejection = (reason: Error) => {
       unhandled = reason;
     };
     process.once("unhandledRejection", handleUnhandledRejection);