@gencow/core 0.1.24 → 0.1.26

package/src/reactive.ts

@@ -6,16 +6,16 @@ import { type Validator, type InferArgs } from "./v.js";
 // ─── GencowCtx — 사용자 함수에 주입되는 컨텍스트 ──────────
 
 export interface UserIdentity {
-    id: string;
-    email: string;
-    name?: string;
+  id: string;
+  email: string;
+  name?: string;
 }
 
 export interface AuthCtx {
-    /** 현재 유저 반환 (비로그인 시 null) — Convex의 ctx.auth.getUserIdentity() */
-    getUserIdentity(): UserIdentity | null;
-    /** 현재 유저 반환 (비로그인 시 401 throw) */
-    requireAuth(): UserIdentity;
+  /** 현재 유저 반환 (비로그인 시 null) — Convex의 ctx.auth.getUserIdentity() */
+  getUserIdentity(): UserIdentity | null;
+  /** 현재 유저 반환 (비로그인 시 401 throw) */
+  requireAuth(): UserIdentity;
 }
 
 /**
@@ -23,36 +23,36 @@ export interface AuthCtx {
  * 클라이언트는 이 데이터를 받아 re-fetch 없이 state를 업데이트합니다.
  */
 export interface RealtimeCtx {
-    /**
-     * 특정 queryKey를 구독 중인 클라이언트에 데이터를 즉시 push합니다.
-     * 초고빈도 mutation (채팅 등)에서 query re-run 비용을 회피할 때 사용.
-     *
-     * @param queryKey - 업데이트할 쿼리 키 (예: "tasks.list")
-     * @param data     - push할 데이터 (해당 query 결과와 동일한 타입)
-     *
-     * @example
-     *   const freshList = await ctx.db.select().from(tasks);
-     *   ctx.realtime.emit("tasks.list", freshList);
-     */
-    emit(queryKey: string, data: unknown): void;
-
-    /**
-     * 수동 mutation에서 리얼타임 업데이트의 기본 권장 방식.
-     * mutation handler 완료 후 서버가 해당 query를 re-run하여 결과를 push합니다.
-     * 복잡한 JOIN query도 queryKey만 지정하면 됩니다.
-     *
-     * @param queryKey - re-run할 쿼리 키 (예: "dashboard.revenue")
-     *
-     * @example
-     *   mutation("orders.place", {
-     *       handler: async (ctx, args) => {
-     *           await ctx.db.insert(orders).values(args);
-     *           ctx.realtime.refresh("orders.list");
-     *           ctx.realtime.refresh("dashboard.revenue");  // JOIN query도 OK
-     *       }
-     *   });
-     */
-    refresh(queryKey: string): void;
+  /**
+   * 특정 queryKey를 구독 중인 클라이언트에 데이터를 즉시 push합니다.
+   * 초고빈도 mutation (채팅 등)에서 query re-run 비용을 회피할 때 사용.
+   *
+   * @param queryKey - 업데이트할 쿼리 키 (예: "tasks.list")
+   * @param data     - push할 데이터 (해당 query 결과와 동일한 타입)
+   *
+   * @example
+   *   const freshList = await ctx.db.select().from(tasks);
+   *   ctx.realtime.emit("tasks.list", freshList);
+   */
+  emit(queryKey: string, data: unknown): void;
+
+  /**
+   * 수동 mutation에서 리얼타임 업데이트의 기본 권장 방식.
+   * mutation handler 완료 후 서버가 해당 query를 re-run하여 결과를 push합니다.
+   * 복잡한 JOIN query도 queryKey만 지정하면 됩니다.
+   *
+   * @param queryKey - re-run할 쿼리 키 (예: "dashboard.revenue")
+   *
+   * @example
+   *   mutation("orders.place", {
+   *       handler: async (ctx, args) => {
+   *           await ctx.db.insert(orders).values(args);
+   *           ctx.realtime.refresh("orders.list");
+   *           ctx.realtime.refresh("dashboard.revenue");  // JOIN query도 OK
+   *       }
+   *   });
+   */
+  refresh(queryKey: string): void;
 }
 
 /**
@@ -63,59 +63,57 @@ export interface RealtimeCtx {
 // ─── AI Context ─────────────────────────────────────────
 
 export interface AIMessage {
-    role: "user" | "system" | "assistant";
-    content: string;
+  role: "user" | "system" | "assistant";
+  content: string;
 }
 
 export interface AIResult {
-    text: string;
-    usage: { promptTokens: number; completionTokens: number; totalTokens: number };
-    creditsCharged: number;
-    model: string;
+  text: string;
+  usage: { promptTokens: number; completionTokens: number; totalTokens: number };
+  creditsCharged: number;
+  model: string;
 }
 
 export interface AIContext {
-    /** AI 텍스트 생성 */
-    chat: (opts: {
-        model?: string;
-        messages: AIMessage[];
-        /** System prompt — shorthand for adding a system message */
-        system?: string;
-        temperature?: number;
-        maxTokens?: number;
-        /** Response format — e.g. { type: "json_object" } for JSON mode */
-        responseFormat?: { type: string };
-    }) => Promise<AIResult>;
-    /** 텍스트 임베딩 (단일) */
-    embed: (text: string) => Promise<number[]>;
-    /** 배치 임베딩 */
-    embedMany: (texts: string[]) => Promise<number[][]>;
+  /** AI 텍스트 생성 */
+  chat: (opts: {
+    model?: string;
+    messages: AIMessage[];
+    /** System prompt — shorthand for adding a system message */
+    system?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Response format — e.g. { type: "json_object" } for JSON mode */
+    responseFormat?: { type: string };
+  }) => Promise<AIResult>;
+  /** 텍스트 임베딩 (단일) */
+  embed: (text: string) => Promise<number[]>;
+  /** 배치 임베딩 */
+  embedMany: (texts: string[]) => Promise<number[][]>;
 }
 
 export interface GencowCtx {
-    /** Drizzle DB 인스턴스 (scoped) — 스키마 filter 자동 적용, execute 차단 */
-    db: any; // typed per-app via generic
-    /** Raw Drizzle DB — 필터 없음, execute 허용. ⚠️ 이름이 곧 경고. */
-    unsafeDb: any;
-    /** 인증 컨텍스트 — ctx.auth.getUserIdentity() */
-    auth: AuthCtx;
-    /** 파일 스토리지 — ctx.storage.store(), ctx.storage.getUrl() */
-    storage: Storage;
-    /** 스케줄러 — ctx.scheduler.runAfter(), ctx.scheduler.cron() */
-    scheduler: Scheduler;
-    /** 실시간 push — ctx.realtime.emit(queryKey, data) */
-    realtime: RealtimeCtx;
-    /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
-    retry: <T>(fn: () => Promise<T>, options?: import("./retry.js").RetryOptions) => Promise<T>;
-    /** AI 헬퍼 */
-    ai?: AIContext;
+  /** Drizzle DB 인스턴스 (scoped) — 스키마 filter 자동 적용, execute 차단 */
+  db: any; // typed per-app via generic
+  /** Raw Drizzle DB — 필터 없음, execute 허용. ⚠️ 이름이 곧 경고. */
+  unsafeDb: any;
+  /** 인증 컨텍스트 — ctx.auth.getUserIdentity() */
+  auth: AuthCtx;
+  /** 파일 스토리지 — ctx.storage.store(), ctx.storage.getUrl() */
+  storage: Storage;
+  /** 스케줄러 — ctx.scheduler.runAfter(), ctx.scheduler.cron() */
+  scheduler: Scheduler;
+  /** 실시간 push — ctx.realtime.emit(queryKey, data) */
+  realtime: RealtimeCtx;
+  /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
+  retry: <T>(fn: () => Promise<T>, options?: import("./retry.js").RetryOptions) => Promise<T>;
+  /** AI 헬퍼 */
+  ai?: AIContext;
 }
 
 // ─── Types ──────────────────────────────────────────────
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
 
 /**
@@ -125,63 +123,63 @@ type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs)
 export type HttpActionHandler = (ctx: GencowCtx, req: HttpActionRequest) => Promise<HttpActionResponse>;
 
 export interface HttpActionRequest {
-    /** HTTP method (GET, POST, PUT, DELETE, PATCH) */
-    method: string;
-    /** Full URL */
-    url: string;
-    /** URL path (e.g. /api/cli/auth-start) */
-    path: string;
-    /** Route params (e.g. { id: "abc" } for /api/apps/:id) */
-    params: Record<string, string>;
-    /** Query string params */
-    query: Record<string, string>;
-    /** Request headers */
-    headers: Record<string, string>;
-    /** Parse JSON body */
-    json: <T = unknown>() => Promise<T>;
-    /** Parse form data */
-    formData: () => Promise<FormData>;
-    /** Raw body as ArrayBuffer */
-    arrayBuffer: () => Promise<ArrayBuffer>;
-    /** Raw body as text */
-    text: () => Promise<string>;
+  /** HTTP method (GET, POST, PUT, DELETE, PATCH) */
+  method: string;
+  /** Full URL */
+  url: string;
+  /** URL path (e.g. /api/cli/auth-start) */
+  path: string;
+  /** Route params (e.g. { id: "abc" } for /api/apps/:id) */
+  params: Record<string, string>;
+  /** Query string params */
+  query: Record<string, string>;
+  /** Request headers */
+  headers: Record<string, string>;
+  /** Parse JSON body */
+  json: <T = unknown>() => Promise<T>;
+  /** Parse form data */
+  formData: () => Promise<FormData>;
+  /** Raw body as ArrayBuffer */
+  arrayBuffer: () => Promise<ArrayBuffer>;
+  /** Raw body as text */
+  text: () => Promise<string>;
 }
 
 export interface HttpActionResponse {
-    status?: number;
-    headers?: Record<string, string>;
-    body?: unknown;
+  status?: number;
+  headers?: Record<string, string>;
+  body?: unknown;
 }
 
 export interface QueryDef<TSchema = any, TReturn = any> {
-    key: string;
-    handler: QueryHandler<InferArgs<TSchema>, TReturn>;
-    argsSchema?: TSchema;
-    /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
-    isPublic: boolean;
-    _args?: InferArgs<TSchema>;
-    _return?: TReturn;
+  key: string;
+  handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+  argsSchema?: TSchema;
+  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
+  isPublic: boolean;
+  _args?: InferArgs<TSchema>;
+  _return?: TReturn;
 }
 
 export interface MutationDef<TSchema = any, TReturn = any> {
-    handler: MutationHandler<InferArgs<TSchema>, TReturn>;
-    argsSchema?: TSchema;
-    /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
-    isPublic: boolean;
-    _args?: InferArgs<TSchema>;
-    _return?: TReturn;
+  handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+  argsSchema?: TSchema;
+  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
+  isPublic: boolean;
+  _args?: InferArgs<TSchema>;
+  _return?: TReturn;
 }
 
 /** httpAction 정의. 커스텀 HTTP 엔드포인트를 선언적으로 등록. */
 export interface HttpActionDef {
-    /** HTTP method */
-    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-    /** URL path (Hono 패턴 — /api/cli/:code 형태 지원) */
-    path: string;
-    /** true = 인증 없이 접근 가능, false(기본) = auth 필수 */
-    isPublic: boolean;
-    /** 핸들러 */
-    handler: HttpActionHandler;
+  /** HTTP method */
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  /** URL path (Hono 패턴 — /api/cli/:code 형태 지원) */
+  path: string;
+  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 */
+  isPublic: boolean;
+  /** 핸들러 */
+  handler: HttpActionHandler;
 }
 
 // ─── Registry ───────────────────────────────────────────
@@ -191,16 +189,11 @@ export interface HttpActionDef {
 // See: docs/analysis/analysis-dual-module-registry.md
 
 declare global {
-    // eslint-disable-next-line no-var
-    var __gencow_queryRegistry: Map<string, QueryDef<any, any>>;
-    // eslint-disable-next-line no-var
-    var __gencow_mutationRegistry: (MutationDef<any, any> & { name: string })[];
-    // eslint-disable-next-line no-var
-    var __gencow_subscribers: Map<string, Set<WSContext>>;
-    // eslint-disable-next-line no-var
-    var __gencow_connectedClients: Set<WSContext>;
-    // eslint-disable-next-line no-var
-    var __gencow_httpActionRegistry: HttpActionDef[];
+  var __gencow_queryRegistry: Map<string, QueryDef<any, any>>;
+  var __gencow_mutationRegistry: (MutationDef<any, any> & { name: string })[];
+  var __gencow_subscribers: Map<string, Set<WSContext>>;
+  var __gencow_connectedClients: Set<WSContext>;
+  var __gencow_httpActionRegistry: HttpActionDef[];
 }
 
 if (!globalThis.__gencow_queryRegistry) globalThis.__gencow_queryRegistry = new Map();
@@ -224,24 +217,26 @@ const connectedClients = globalThis.__gencow_connectedClients;
 // ─── Public API (Convex-style) ──────────────────────────
 
 export function query<TSchema = any, TReturn = any>(
-    key: string,
-    handlerOrDef: QueryHandler<InferArgs<TSchema>, TReturn> | { args?: TSchema; public?: boolean; handler: QueryHandler<InferArgs<TSchema>, TReturn> }
+  key: string,
+  handlerOrDef:
+    | QueryHandler<InferArgs<TSchema>, TReturn>
+    | { args?: TSchema; public?: boolean; handler: QueryHandler<InferArgs<TSchema>, TReturn> },
 ): QueryDef<TSchema, TReturn> {
-    let handler: QueryHandler<InferArgs<TSchema>, TReturn>;
-    let argsSchema: TSchema | undefined;
-    let isPublic = false;
-
-    if (typeof handlerOrDef === "function") {
-        handler = handlerOrDef;
-    } else {
-        handler = handlerOrDef.handler;
-        argsSchema = handlerOrDef.args;
-        isPublic = handlerOrDef.public === true;
-    }
-
-    const def: QueryDef<TSchema, TReturn> = { key, handler, argsSchema, isPublic };
-    queryRegistry.set(key, def);
-    return def;
+  let handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+  let argsSchema: TSchema | undefined;
+  let isPublic = false;
+
+  if (typeof handlerOrDef === "function") {
+    handler = handlerOrDef;
+  } else {
+    handler = handlerOrDef.handler;
+    argsSchema = handlerOrDef.args;
+    isPublic = handlerOrDef.public === true;
+  }
+
+  const def: QueryDef<TSchema, TReturn> = { key, handler, argsSchema, isPublic };
+  queryRegistry.set(key, def);
+  return def;
 }
 
 let mutationCounter = 0;
@@ -273,50 +268,73 @@ let mutationCounter = 0;
  *       리얼타임 UI 갱신에는 ctx.realtime.emit() 또는 ctx.realtime.refresh()를 사용하세요.
  */
 export function mutation<TSchema = any, TReturn = any>(
-    nameOrInvalidatesOrDef: string | string[] | { name?: string; args?: TSchema; public?: boolean; invalidates?: string[]; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
-    handlerOrDef?: MutationHandler<InferArgs<TSchema>, TReturn> | { invalidates?: string[]; args?: TSchema; public?: boolean; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
-    name?: string
+  nameOrInvalidatesOrDef:
+    | string
+    | string[]
+    | {
+        name?: string;
+        args?: TSchema;
+        public?: boolean;
+        invalidates?: string[];
+        handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+      },
+  handlerOrDef?:
+    | MutationHandler<InferArgs<TSchema>, TReturn>
+    | {
+        invalidates?: string[];
+        args?: TSchema;
+        public?: boolean;
+        handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+      },
+  name?: string,
 ): MutationDef<TSchema, TReturn> {
-    let argsSchema: TSchema | undefined;
-    let actualHandler: MutationHandler<InferArgs<TSchema>, TReturn>;
-    let mutName: string;
-    let isPublic = false;
-
-    if (typeof nameOrInvalidatesOrDef === "string") {
-        // New primary style: mutation("name", { args?, public?, handler })
-        mutName = nameOrInvalidatesOrDef;
-        const def = handlerOrDef as { args?: TSchema; public?: boolean; handler: MutationHandler<InferArgs<TSchema>, TReturn> };
-        actualHandler = def.handler;
-        argsSchema = def.args;
-        isPublic = def.public === true;
-    } else if (Array.isArray(nameOrInvalidatesOrDef)) {
-        // Legacy style: mutation([...], handler, "name") — invalidates ignored
-        actualHandler = handlerOrDef as MutationHandler<InferArgs<TSchema>, TReturn>;
-        mutName = name || `mutation_${++mutationCounter}`;
-    } else {
-        // Object style: mutation({ name?, args?, public?, handler })
-        actualHandler = nameOrInvalidatesOrDef.handler;
-        argsSchema = nameOrInvalidatesOrDef.args;
-        isPublic = nameOrInvalidatesOrDef.public === true;
-        mutName = nameOrInvalidatesOrDef.name || (typeof name === "string" ? name : "") || `mutation_${++mutationCounter}`;
-    }
-
-    // 이름 미지정 시 경고 — 디버깅 지원
-    if (mutName.startsWith("mutation_")) {
-        console.warn(
-            `[gencow] mutation registered without explicit name → "${mutName}". ` +
-            `Use mutation("myMutation", { handler }) for better debugging.`
-        );
-    }
-
-    const def: MutationDef<TSchema, TReturn> & { name: string } = {
-        name: mutName,
-        handler: actualHandler,
-        argsSchema,
-        isPublic,
+  let argsSchema: TSchema | undefined;
+  let actualHandler: MutationHandler<InferArgs<TSchema>, TReturn>;
+  let mutName: string;
+  let isPublic = false;
+
+  if (typeof nameOrInvalidatesOrDef === "string") {
+    // New primary style: mutation("name", { args?, public?, handler })
+    mutName = nameOrInvalidatesOrDef;
+    const def = handlerOrDef as {
+      args?: TSchema;
+      public?: boolean;
+      handler: MutationHandler<InferArgs<TSchema>, TReturn>;
     };
-    mutationRegistry.push(def);
-    return def;
+    actualHandler = def.handler;
+    argsSchema = def.args;
+    isPublic = def.public === true;
+  } else if (Array.isArray(nameOrInvalidatesOrDef)) {
+    // Legacy style: mutation([...], handler, "name") — invalidates ignored
+    actualHandler = handlerOrDef as MutationHandler<InferArgs<TSchema>, TReturn>;
+    mutName = name || `mutation_${++mutationCounter}`;
+  } else {
+    // Object style: mutation({ name?, args?, public?, handler })
+    actualHandler = nameOrInvalidatesOrDef.handler;
+    argsSchema = nameOrInvalidatesOrDef.args;
+    isPublic = nameOrInvalidatesOrDef.public === true;
+    mutName =
+      nameOrInvalidatesOrDef.name ||
+      (typeof name === "string" ? name : "") ||
+      `mutation_${++mutationCounter}`;
+  }
+
+  // 이름 미지정 시 경고 — 디버깅 지원
+  if (mutName.startsWith("mutation_")) {
+    console.warn(
+      `[gencow] mutation registered without explicit name → "${mutName}". ` +
+        `Use mutation("myMutation", { handler }) for better debugging.`,
+    );
+  }
+
+  const def: MutationDef<TSchema, TReturn> & { name: string } = {
+    name: mutName,
+    handler: actualHandler,
+    argsSchema,
+    isPublic,
+  };
+  mutationRegistry.push(def);
+  return def;
 }
 
 // ─── httpAction (커스텀 HTTP 엔드포인트) ────────────────
@@ -347,52 +365,52 @@ export function mutation<TSchema = any, TReturn = any>(
  * ```
  */
 export function httpAction(def: {
-    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-    path: string;
-    public?: boolean;
-    handler: HttpActionHandler;
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  path: string;
+  public?: boolean;
+  handler: HttpActionHandler;
 }): HttpActionDef {
-    const actionDef: HttpActionDef = {
-        method: def.method,
-        path: def.path,
-        isPublic: def.public === true,
-        handler: def.handler,
-    };
-    httpActionRegistry.push(actionDef);
-    return actionDef;
+  const actionDef: HttpActionDef = {
+    method: def.method,
+    path: def.path,
+    isPublic: def.public === true,
+    handler: def.handler,
+  };
+  httpActionRegistry.push(actionDef);
+  return actionDef;
 }
 
 export function getRegisteredHttpActions(): HttpActionDef[] {
-    return [...httpActionRegistry];
+  return [...httpActionRegistry];
 }
 
 // ─── WebSocket subscription management ──────────────────
 
 export function subscribe(queryKey: string, ws: WSContext) {
-    connectedClients.add(ws);
-    if (!subscribers.has(queryKey)) {
-        subscribers.set(queryKey, new Set());
-    }
-    subscribers.get(queryKey)!.add(ws);
+  connectedClients.add(ws);
+  if (!subscribers.has(queryKey)) {
+    subscribers.set(queryKey, new Set());
+  }
+  subscribers.get(queryKey)!.add(ws);
 }
 
 export function unsubscribe(ws: WSContext) {
-    connectedClients.delete(ws);
-    for (const clients of subscribers.values()) {
-        clients.delete(ws);
-    }
+  connectedClients.delete(ws);
+  for (const clients of subscribers.values()) {
+    clients.delete(ws);
+  }
 }
 
 /** Register a raw WS connection without any query subscription (e.g. admin dashboard) */
 export function registerClient(ws: WSContext) {
-    connectedClients.add(ws);
+  connectedClients.add(ws);
 }
 
 export function deregisterClient(ws: WSContext) {
-    connectedClients.delete(ws);
-    for (const clients of subscribers.values()) {
-        clients.delete(ws);
-    }
+  connectedClients.delete(ws);
+  for (const clients of subscribers.values()) {
+    clients.delete(ws);
+  }
 }
 
 /**
@@ -412,143 +430,151 @@ export function deregisterClient(ws: WSContext) {
  * @param options.buildCtxForRefresh  refresh 시 query handler에 전달할 ctx 생성 함수.
  */
 export function buildRealtimeCtx(options?: {
-    httpCallback?: (event: { type: "emit"; queryKey: string; data: unknown }) => void;
-    queryMap?: Map<string, QueryDef<any, any>>;
-    buildCtxForRefresh?: () => GencowCtx;
+  httpCallback?: (event: { type: "emit"; queryKey: string; data: unknown }) => void;
+  queryMap?: Map<string, QueryDef<any, any>>;
+  buildCtxForRefresh?: () => GencowCtx;
 }): RealtimeCtx & { _hasEmitted: boolean; _pendingRefresh: string[]; _flushRefresh: () => Promise<void> } {
-    const pendingEmits = new Map<string, { data: unknown; timer: ReturnType<typeof setTimeout> }>();
-    const _pendingRefresh: string[] = [];
-    let _hasEmitted = false;
-
-    return {
-        emit(queryKey: string, data: unknown) {
-            _hasEmitted = true;
-            // 기존 pending timer가 있으면 취소 (debounce)
-            const existing = pendingEmits.get(queryKey);
-            if (existing) clearTimeout(existing.timer);
-
-            const timer = setTimeout(() => {
-                pendingEmits.delete(queryKey);
-
-                // BaaS 모드: Platform WS Gateway에 HTTP callback
-                if (options?.httpCallback) {
-                    options.httpCallback({ type: "emit", queryKey, data });
-                    return;
-                }
-
-                // 로컬 dev: WS 직접 push (기존 동작)
-                const clients = subscribers.get(queryKey);
-                if (!clients || clients.size === 0) return;
-
-                const message = JSON.stringify({
-                    type: "query:updated",
-                    query: queryKey,
-                    data,
-                });
-                for (const ws of clients) {
-                    try { ws.send(message); } catch { clients.delete(ws); }
-                }
-            }, 50); // 50ms batch window
-
-            pendingEmits.set(queryKey, { data, timer });
-        },
-
-        refresh(queryKey: string) {
-            _hasEmitted = true;  // 경고 억제
-            if (!_pendingRefresh.includes(queryKey)) {
-                _pendingRefresh.push(queryKey);
-            }
-        },
-
-        get _hasEmitted() { return _hasEmitted; },
-        get _pendingRefresh() { return [..._pendingRefresh]; },
-
-        async _flushRefresh() {
-            if (_pendingRefresh.length === 0) return;
-
-            // queryMap이 없으면 refresh 동작 불가 (로그 경고)
-            const qMap = options?.queryMap ?? queryRegistry;
+  const pendingEmits = new Map<string, { data: unknown; timer: ReturnType<typeof setTimeout> }>();
+  const _pendingRefresh: string[] = [];
+  let _hasEmitted = false;
+
+  return {
+    emit(queryKey: string, data: unknown) {
+      _hasEmitted = true;
+      // 기존 pending timer가 있으면 취소 (debounce)
+      const existing = pendingEmits.get(queryKey);
+      if (existing) clearTimeout(existing.timer);
+
+      const timer = setTimeout(() => {
+        pendingEmits.delete(queryKey);
+
+        // BaaS 모드: Platform WS Gateway에 HTTP callback
+        if (options?.httpCallback) {
+          options.httpCallback({ type: "emit", queryKey, data });
+          return;
+        }
 
-            for (const key of _pendingRefresh) {
-                const queryDef = qMap.get(key);
-                if (!queryDef) {
-                    console.warn(`[gencow] refresh("${key}"): query not found in registry. Skipping.`);
-                    continue;
-                }
+        // 로컬 dev: WS 직접 push (기존 동작)
+        const clients = subscribers.get(queryKey);
+        if (!clients || clients.size === 0) return;
+
+        const message = JSON.stringify({
+          type: "query:updated",
+          query: queryKey,
+          data,
+        });
+        for (const ws of clients) {
+          try {
+            ws.send(message);
+          } catch {
+            clients.delete(ws);
+          }
+        }
+      }, 50); // 50ms batch window
+
+      pendingEmits.set(queryKey, { data, timer });
+    },
+
+    refresh(queryKey: string) {
+      _hasEmitted = true; // 경고 억제
+      if (!_pendingRefresh.includes(queryKey)) {
+        _pendingRefresh.push(queryKey);
+      }
+    },
+
+    get _hasEmitted() {
+      return _hasEmitted;
+    },
+    get _pendingRefresh() {
+      return [..._pendingRefresh];
+    },
+
+    async _flushRefresh() {
+      if (_pendingRefresh.length === 0) return;
+
+      // queryMap이 없으면 refresh 동작 불가 (로그 경고)
+      const qMap = options?.queryMap ?? queryRegistry;
+
+      for (const key of _pendingRefresh) {
+        const queryDef = qMap.get(key);
+        if (!queryDef) {
+          console.warn(`[gencow] refresh("${key}"): query not found in registry. Skipping.`);
+          continue;
+        }
+        try {
+          // refresh용 ctx 생성 (mutation ctx와 동일한 DB/auth 스코프)
+          if (!options?.buildCtxForRefresh) {
+            console.warn(
+              `[gencow] ⚠️  refresh("${key}"): buildCtxForRefresh not provided. ` +
+                `Query handler will receive an empty ctx — ctx.db will be undefined. ` +
+                `This is a framework configuration error. ` +
+                `💡 Ensure buildRealtimeCtx() receives a buildCtxForRefresh callback.`,
+            );
+          }
+          const refreshCtx = options?.buildCtxForRefresh?.() ?? ({} as GencowCtx);
+          const result = await queryDef.handler(refreshCtx, {});
+
+          // emit과 동일한 경로로 push
+          if (options?.httpCallback) {
+            options.httpCallback({ type: "emit", queryKey: key, data: result });
+          } else {
+            const clients = subscribers.get(key);
+            if (clients && clients.size > 0) {
+              const message = JSON.stringify({
+                type: "query:updated",
+                query: key,
+                data: result,
+              });
+              for (const ws of clients) {
                 try {
-                    // refresh용 ctx 생성 (mutation ctx와 동일한 DB/auth 스코프)
-                    if (!options?.buildCtxForRefresh) {
-                        console.warn(
-                            `[gencow] ⚠️  refresh("${key}"): buildCtxForRefresh not provided. ` +
-                            `Query handler will receive an empty ctx — ctx.db will be undefined. ` +
-                            `This is a framework configuration error. ` +
-                            `💡 Ensure buildRealtimeCtx() receives a buildCtxForRefresh callback.`
-                        );
-                    }
-                    const refreshCtx = options?.buildCtxForRefresh?.() ?? ({} as GencowCtx);
-                    const result = await queryDef.handler(refreshCtx, {});
-
-                    // emit과 동일한 경로로 push
-                    if (options?.httpCallback) {
-                        options.httpCallback({ type: "emit", queryKey: key, data: result });
-                    } else {
-                        const clients = subscribers.get(key);
-                        if (clients && clients.size > 0) {
-                            const message = JSON.stringify({
-                                type: "query:updated",
-                                query: key,
-                                data: result,
-                            });
-                            for (const ws of clients) {
-                                try { ws.send(message); } catch { clients.delete(ws); }
-                            }
-                        }
-                    }
-                } catch (e) {
-                    console.warn(`[gencow] refresh("${key}") failed:`, e instanceof Error ? e.message : e);
+                  ws.send(message);
+                } catch {
+                  clients.delete(ws);
                 }
+              }
             }
-            _pendingRefresh.length = 0;
-        },
-    };
+          }
+        } catch (e) {
+          console.warn(`[gencow] refresh("${key}") failed:`, e instanceof Error ? e.message : e);
+        }
+      }
+      _pendingRefresh.length = 0;
+    },
+  };
 }
 
-
 // ─── WebSocket message handler ──────────────────────────
 
 export function handleWsMessage(ws: WSContext, raw: string | ArrayBuffer) {
-    try {
-        const msg =
-            typeof raw === "string" ? JSON.parse(raw) : JSON.parse(raw.toString());
-
-        if (msg.type === "subscribe" && msg.query) {
-            subscribe(msg.query, ws);
-            ws.send(
-                JSON.stringify({ type: "subscribed", query: msg.query })
-            );
-        }
+  try {
+    const msg = typeof raw === "string" ? JSON.parse(raw) : JSON.parse(raw.toString());
 
-        if (msg.type === "unsubscribe" && msg.query) {
-            const clients = subscribers.get(msg.query);
-            if (clients) clients.delete(ws);
-        }
-    } catch {
-        // ignore malformed messages
+    if (msg.type === "subscribe" && msg.query) {
+      subscribe(msg.query, ws);
+      ws.send(JSON.stringify({ type: "subscribed", query: msg.query }));
+    }
+
+    if (msg.type === "unsubscribe" && msg.query) {
+      const clients = subscribers.get(msg.query);
+      if (clients) clients.delete(ws);
     }
+  } catch {
+    // ignore malformed messages
+  }
 }
 
 export function getQueryHandler(key: string): QueryHandler | undefined {
-    return queryRegistry.get(key)?.handler;
+  return queryRegistry.get(key)?.handler;
 }
 
 export function getQueryDef(key: string): QueryDef | undefined {
-    return queryRegistry.get(key);
+  return queryRegistry.get(key);
 }
 
 export function getRegisteredQueries(): string[] {
-    return Array.from(queryRegistry.keys());
+  return Array.from(queryRegistry.keys());
 }
 
 export function getRegisteredMutations(): (MutationDef & { name: string })[] {
-    return [...mutationRegistry];
+  return [...mutationRegistry];
 }