@gencow/core 0.1.17 → 0.1.18

package/src/__tests__/reactive.test.ts

@@ -1,13 +1,13 @@
 /**
  * packages/core/src/__tests__/reactive.test.ts
  *
- * Tests for ctx.realtime.emit() push model and invalidateQueries() simplification.
+ * Tests for ctx.realtime.emit() push model and refresh() API.
  *
  * Run: bun test packages/core/src/__tests__/reactive.test.ts
  */
 
 import { describe, it, expect, mock, beforeEach } from "bun:test";
-import { buildRealtimeCtx, invalidateQueries, subscribe, deregisterClient, registerClient } from "../reactive";
+import { buildRealtimeCtx, subscribe, deregisterClient, registerClient } from "../reactive";
 import type { GencowCtx } from "../reactive";
 
 // ─── Mock WebSocket (Bun-style WSContext) ────────────────────────────────────
@@ -96,78 +96,63 @@ describe("buildRealtimeCtx()", () => {
     });
 });
 
-// ─── invalidateQueries (simplified) ─────────────────────────────────────────
+// ─── refresh() API ──────────────────────────────────────────────────────────
 
-describe("invalidateQueries() — simplified broadcast-only", () => {
-    it("빈 배열이면 아무것도 전송하지 않는다 (emit() 방식 no-op)", async () => {
-        const ws = makeMockWs();
-        registerClient(ws);
-
-        const mockCtx = {} as GencowCtx;
-        await invalidateQueries([], mockCtx);
+describe("refresh() — 서버 쿼리 재실행 요청 큐", () => {
+    it("refresh()로 등록된 queryKey가 _pendingRefresh에 큐잉된다", () => {
+        const rt = buildRealtimeCtx();
+        rt.refresh("tasks.list");
 
-        expect(ws._sent).toHaveLength(0);
-        deregisterClient(ws);
+        expect((rt as any)._pendingRefresh).toContain("tasks.list");
     });
 
-    it("queryKeys가 있으면 connectedClients 전체에 invalidate broadcast를 보낸다", async () => {
-        const ws = makeMockWs();
-        registerClient(ws);
-
-        const mockCtx = {} as GencowCtx;
-        await invalidateQueries(["tasks.list"], mockCtx);
-
-        expect(ws._sent).toHaveLength(1);
-        const msg = JSON.parse(ws._sent[0]);
-        expect(msg.type).toBe("invalidate");
-        expect(msg.queries).toEqual(["tasks.list"]);
+    it("동일 queryKey 중복 refresh는 한 번만 큐잉된다", () => {
+        const rt = buildRealtimeCtx();
+        rt.refresh("tasks.list");
+        rt.refresh("tasks.list");
+        rt.refresh("tasks.list");
 
-        deregisterClient(ws);
+        const count = (rt as any)._pendingRefresh.filter((k: string) => k === "tasks.list").length;
+        expect(count).toBe(1);
     });
 
-    it("서버에서 쿼리를 재실행하지 않는다 (query:updated 미전송)", async () => {
-        const ws = makeMockWs();
-        registerClient(ws);
-
-        const mockCtx = {} as GencowCtx;
-        await invalidateQueries(["tasks.list", "tasks.get"], mockCtx);
-
-        // query:updated 메시지가 없어야 함
-        const types = ws._sent.map((s: string) => JSON.parse(s).type);
-        expect(types.every((t: string) => t === "invalidate")).toBe(true);
+    it("서로 다른 queryKey는 각각 큐잉된다", () => {
+        const rt = buildRealtimeCtx();
+        rt.refresh("tasks.list");
+        rt.refresh("users.list");
 
-        deregisterClient(ws);
+        expect((rt as any)._pendingRefresh).toContain("tasks.list");
+        expect((rt as any)._pendingRefresh).toContain("users.list");
     });
 });
 
-// ─── buildRealtimeCtx + invalidateQueries 공존 시나리오 ─────────────────────
-
-describe("emit() 방식과 legacy invalidateQueries() 혼용", () => {
-    it("emit()은 query:updated, invalidateQueries()는 invalidate를 각각 전송한다", async () => {
-        const wsSubscribed = makeMockWs(); // query 구독 클라이언트
-        const wsConnected = makeMockWs(); // 연결만 된 클라이언트 (대시보드)
+// ─── emit()과 refresh() 병행 시나리오 ───────────────────────────────────────
 
+describe("emit()과 refresh() 병행", () => {
+    it("emit()은 query:updated를 구독자에게 즉시 push한다", async () => {
+        const wsSubscribed = makeMockWs();
         subscribe("items.list", wsSubscribed);
-        registerClient(wsConnected);
 
-        // 1. emit() — 구독자에게만 query:updated
         const rt = buildRealtimeCtx();
         rt.emit("items.list", [{ id: 1 }]);
         await new Promise(r => setTimeout(r, 80));
 
         expect(wsSubscribed._sent.some((s: string) => JSON.parse(s).type === "query:updated")).toBe(true);
-        // connectedClients에만 등록된 ws는 query:updated 미수신
-        expect(wsConnected._sent).toHaveLength(0);
 
-        // 2. invalidateQueries() — ALL connectedClients에 invalidate broadcast
-        const mockCtx = {} as GencowCtx;
-        await invalidateQueries(["items.list"], mockCtx);
+        deregisterClient(wsSubscribed);
+    });
 
-        expect(wsConnected._sent).toHaveLength(1);
-        expect(JSON.parse(wsConnected._sent[0]).type).toBe("invalidate");
+    it("emit() 호출 후 _hasEmitted가 true로 설정된다", () => {
+        const rt = buildRealtimeCtx();
+        expect((rt as any)._hasEmitted).toBe(false);
 
-        deregisterClient(wsSubscribed);
-        deregisterClient(wsConnected);
+        const ws = makeMockWs();
+        subscribe("flag.test", ws);
+        rt.emit("flag.test", [{ id: 1 }]);
+
+        expect((rt as any)._hasEmitted).toBe(true);
+
+        deregisterClient(ws);
     });
 });
 
@@ -206,7 +191,6 @@ describe("Secure by Default — public 플래그", () => {
     it("mutation() 기본값은 isPublic === false", () => {
         const m = mutation({
             name: "sectest.mut.private",
-            invalidates: [],
             handler: async () => ({ ok: true }),
         });
         expect(m.isPublic).toBe(false);
@@ -215,7 +199,6 @@ describe("Secure by Default — public 플래그", () => {
     it("mutation({ public: true }) 시 isPublic === true", () => {
         const m = mutation({
             name: "sectest.mut.public",
-            invalidates: [],
             public: true,
             handler: async () => ({ ok: true }),
         });
@@ -243,7 +226,7 @@ describe("mutation(name, def) — query와 동일 패턴", () => {
         const m = mutation("newsig.basic", {
             handler: async () => ({ ok: true }),
         });
-        expect((m as any).name || (getRegisteredMutations().find(x => x.invalidates.length === 0 && x.handler === (m as any).handler) as any)?.name).toBeDefined();
+        expect((m as any).name || (getRegisteredMutations().find(x => x.handler === (m as any).handler) as any)?.name).toBeDefined();
         const all = getRegisteredMutations();
         const found = all.find(x => x.name === "newsig.basic");
         expect(found).toBeDefined();
@@ -258,35 +241,35 @@ describe("mutation(name, def) — query와 동일 패턴", () => {
         expect(m.isPublic).toBe(true);
     });
 
-    it("invalidates 미지정 시 빈 배열이 기본값", () => {
+    it("invalidates 미지정 시 빈 배열이 기본값 (하위호환)", () => {
         const m = mutation("newsig.noInvalidates", {
             handler: async () => ({ ok: true }),
         });
         const all = getRegisteredMutations();
         const found = all.find(x => x.name === "newsig.noInvalidates");
-        expect(found!.invalidates).toEqual([]);
+        // invalidates는 deprecated이지만 빈 배열로 유지 (하위호환)
+        expect(found).toBeDefined();
     });
 
-    it("invalidates 지정 시 올바르게 전달된다", () => {
+    it("invalidates 지정해도 무시된다 (deprecated)", () => {
         const m = mutation("newsig.withInvalidates", {
             invalidates: ["tasks.list", "tasks.get"],
             handler: async () => ({ ok: true }),
         });
         const all = getRegisteredMutations();
         const found = all.find(x => x.name === "newsig.withInvalidates");
-        expect(found!.invalidates).toEqual(["tasks.list", "tasks.get"]);
+        // invalidates는 deprecated — 전달해도 런타임에서 무시됨
+        expect(found).toBeDefined();
     });
 
     it("기존 객체 스타일도 여전히 동작한다 (하위 호환)", () => {
         const m = mutation({
             name: "newsig.compat.object",
-            invalidates: ["a.list"],
             handler: async () => ({ ok: true }),
         });
         const all = getRegisteredMutations();
         const found = all.find(x => x.name === "newsig.compat.object");
         expect(found).toBeDefined();
-        expect(found!.invalidates).toEqual(["a.list"]);
     });
 
     it("기존 배열 스타일도 여전히 동작한다 (하위 호환)", () => {
@@ -294,7 +277,6 @@ describe("mutation(name, def) — query와 동일 패턴", () => {
         const all = getRegisteredMutations();
         const found = all.find(x => x.name === "newsig.compat.array");
         expect(found).toBeDefined();
-        expect(found!.invalidates).toEqual(["b.list"]);
     });
 
     it("이름 미지정 시 console.warn이 호출된다", () => {

package/src/crud.ts

@@ -354,7 +354,6 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
 
     const createDef = !enabledMethods.has('create') ? undefined : mutation(`${prefix}.create`, {
         public: isPublic,
-        invalidates: [],
         handler: async (ctx: any, args: any) => {
             const user = isPublic ? null : ctx.auth.requireAuth();
 
@@ -386,7 +385,6 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
 
     const updateDef = !enabledMethods.has('update') ? undefined : mutation(`${prefix}.update`, {
         public: isPublic,
-        invalidates: [],
         handler: async (ctx: any, args: any) => {
             if (!isPublic) ctx.auth.requireAuth();
 
@@ -428,7 +426,6 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
 
     const removeDef = !enabledMethods.has('remove') ? undefined : mutation(`${prefix}.remove`, {
         public: isPublic,
-        invalidates: [],
         handler: async (ctx: any, args: any) => {
             if (!isPublic) ctx.auth.requireAuth();
 

package/src/index.ts

@@ -6,7 +6,7 @@
  */
 
 export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx, HttpActionDef, HttpActionRequest, HttpActionResponse, HttpActionHandler, AIContext, AIMessage, AIResult } from "./reactive";
-export { query, mutation, httpAction, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive";
+export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive";
 export type { Storage } from "./storage";
 export { createScheduler, getSchedulerInfo } from "./scheduler";
 export type { Scheduler, ScheduleOptions, FailedJob } from "./scheduler";

package/src/reactive.ts

@@ -24,6 +24,9 @@ export interface AuthCtx {
  */
 export interface RealtimeCtx {
     /**
+     * 특정 queryKey를 구독 중인 클라이언트에 데이터를 즉시 push합니다.
+     * 초고빈도 mutation (채팅 등)에서 query re-run 비용을 회피할 때 사용.
+     *
      * @param queryKey - 업데이트할 쿼리 키 (예: "tasks.list")
      * @param data     - push할 데이터 (해당 query 결과와 동일한 타입)
      *
@@ -32,6 +35,24 @@ export interface RealtimeCtx {
      *   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;
 }
 
 /**
@@ -143,7 +164,6 @@ export interface QueryDef<TSchema = any, TReturn = any> {
 }
 
 export interface MutationDef<TSchema = any, TReturn = any> {
-    invalidates: string[];
     handler: MutationHandler<InferArgs<TSchema>, TReturn>;
     argsSchema?: TSchema;
     /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
@@ -235,7 +255,6 @@ let mutationCounter = 0;
  * ```typescript
  * // ✅ 권장: query와 동일한 (name, def) 패턴
  * mutation("tasks.create", {
- *     invalidates: [],
  *     args: { title: v.string() },
  *     handler: async (ctx, args) => { ... },
  * });
@@ -243,41 +262,39 @@ let mutationCounter = 0;
  * // ✅ 객체 스타일 (하위 호환)
  * mutation({
  *     name: "tasks.create",
- *     invalidates: [],
  *     handler: async (ctx) => { ... },
  * });
  *
  * // ⚠️ Legacy 배열 스타일 (비권장)
  * mutation(["tasks.list"], handler, "tasks.create");
  * ```
+ *
+ * @note invalidates 필드는 deprecated — 전달해도 무시됩니다.
+ *       리얼타임 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> },
+    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 invalidates: string[];
     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", { invalidates?, args?, public?, handler })
+        // New primary style: mutation("name", { args?, public?, handler })
         mutName = nameOrInvalidatesOrDef;
-        const def = handlerOrDef as { invalidates?: string[]; args?: TSchema; public?: boolean; handler: MutationHandler<InferArgs<TSchema>, TReturn> };
-        invalidates = def.invalidates || [];
+        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 = nameOrInvalidatesOrDef;
+        // Legacy style: mutation([...], handler, "name") — invalidates ignored
         actualHandler = handlerOrDef as MutationHandler<InferArgs<TSchema>, TReturn>;
         mutName = name || `mutation_${++mutationCounter}`;
     } else {
-        // Object style: mutation({ name?, invalidates, args?, public?, handler })
-        invalidates = nameOrInvalidatesOrDef.invalidates;
+        // Object style: mutation({ name?, args?, public?, handler })
         actualHandler = nameOrInvalidatesOrDef.handler;
         argsSchema = nameOrInvalidatesOrDef.args;
         isPublic = nameOrInvalidatesOrDef.public === true;
@@ -294,7 +311,6 @@ export function mutation<TSchema = any, TReturn = any>(
 
     const def: MutationDef<TSchema, TReturn> & { name: string } = {
         name: mutName,
-        invalidates,
         handler: actualHandler,
         argsSchema,
         isPublic,
@@ -379,14 +395,10 @@ export function deregisterClient(ws: WSContext) {
     }
 }
 
-/**
- * After a mutation, re-run invalidated queries and push results
- * to all subscribers — Convex의 자동 reactive 업데이트 재현
- */
 /**
  * mutation 실행 시점에 생성되는 RealtimeCtx.
- * emit() 호출 시 해당 queryKey를 구독 중인 WebSocket 클라이언트들에게
- * data를 즉시 push합니다.
+ * emit(): 데이터를 직접 push (초고빈도 mutation용).
+ * refresh(): queryKey를 pending 큐에 추가, mutation 완료 후 서버가 query re-run하여 push.
  *
  * 💡 Batching: 같은 queryKey에 대한 emit이 50ms 내에 여러 번 호출되면
  * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
@@ -396,14 +408,21 @@ export function deregisterClient(ws: WSContext) {
  * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
  *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
  *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
+ * @param options.queryMap      query 레지스트리 — refresh()에서 query handler를 찾아 re-run.
+ * @param options.buildCtxForRefresh  refresh 시 query handler에 전달할 ctx 생성 함수.
  */
 export function buildRealtimeCtx(options?: {
     httpCallback?: (event: { type: "emit"; queryKey: string; data: unknown }) => void;
-}): RealtimeCtx {
+    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);
@@ -432,38 +451,58 @@ export function buildRealtimeCtx(options?: {
             }, 50); // 50ms batch window
 
             pendingEmits.set(queryKey, { data, timer });
-        }
-    };
-}
+        },
 
-/**
- * mutation이 끝난 후 호출되는 legacy fallback.
- * `ctx.realtime.emit()`을 사용하는 새 mutation에서는 빈 배열([])을 전달하면 됩니다.
- *
- * invalidate 신호만 broadcast하여 클라이언트가 re-fetch 여부를 결정하게 합니다.
- * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
- *
- * @deprecated ctx.realtime.emit() 사용 권장
- * @param httpInvalidateCallback  BaaS 모드: Platform WS Gateway에 HTTP로 invalidation 전달.
- */
-export async function invalidateQueries(
-    queryKeys: string[],
-    ctx: GencowCtx,
-    httpInvalidateCallback?: (queryKeys: string[]) => void,
-): Promise<void> {
-    if (queryKeys.length === 0) return; // emit() 방식에서는 no-op
-
-    // BaaS 모드: Platform WS Gateway에 HTTP callback
-    if (httpInvalidateCallback) {
-        httpInvalidateCallback(queryKeys);
-        return;
-    }
+        refresh(queryKey: string) {
+            _hasEmitted = true;  // 경고 억제
+            if (!_pendingRefresh.includes(queryKey)) {
+                _pendingRefresh.push(queryKey);
+            }
+        },
 
-    // 로컬 dev: WS 직접 broadcast (기존 동작)
-    const invalidateMsg = JSON.stringify({ type: "invalidate", queries: queryKeys });
-    for (const ws of connectedClients) {
-        try { ws.send(invalidateMsg); } catch { connectedClients.delete(ws); }
-    }
+        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 스코프)
+                    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);
+                }
+            }
+            _pendingRefresh.length = 0;
+        },
+    };
 }