@gencow/core 0.1.17 → 0.1.19

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;
+        },
+    };
 }
 
 

package/src/storage.ts

@@ -52,8 +52,9 @@ export interface Storage {
 const metaStore = new Map<string, StorageFile>();
 
 /**
- * files 테이블 자동 생성 (이미 존재하면 무시)
+ * _system_files 테이블 자동 생성 (이미 존재하면 무시)
  * admin.ts의 CREATE_FILES_TABLE_SQL과 동일한 스키마 사용
+ * ⚠️ 테이블명 '_system_files' — 사용자 테이블과 네이밍 충돌 방지 (2026-04-10)
  */
 let filesTableEnsured = false;
 
@@ -67,9 +68,9 @@ async function ensureFilesTable(
             IF NOT EXISTS (
                 SELECT 1 FROM information_schema.tables
                 WHERE table_schema = current_schema()
-                AND table_name = 'files'
+                AND table_name = '_system_files'
             ) THEN
-                CREATE TABLE files (
+                CREATE TABLE _system_files (
                     id SERIAL PRIMARY KEY,
                     storage_id TEXT NOT NULL,
                     name TEXT NOT NULL,
@@ -95,7 +96,7 @@ async function checkStorageQuota(
     if (quota <= 0) return; // 무제한
 
     const rows = await rawSql(
-        `SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM files`,
+        `SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM _system_files`,
     );
     const currentUsage = Number((rows[0] as Record<string, string>)?.total || "0");
     const projectedUsage = currentUsage + newFileSize;
@@ -124,7 +125,7 @@ async function recordFileToDb(
 ): Promise<void> {
     await ensureFilesTable(rawSql);
     await rawSql(
-        `INSERT INTO files (storage_id, name, size, type, uploaded_by, created_at)
+        `INSERT INTO _system_files (storage_id, name, size, type, uploaded_by, created_at)
          VALUES ($1, $2, $3, $4, $5, NOW())`,
         [storageId, name, String(size), type, uploadedBy],
     );
@@ -258,7 +259,7 @@ export function createStorage(
             if (rawSql) {
                 try {
                     await rawSql(
-                        `DELETE FROM files WHERE storage_id = $1`,
+                        `DELETE FROM _system_files WHERE storage_id = $1`,
                         [storageId],
                     );
                 } catch { /* 삭제 실패 무시 — 파일은 이미 제거됨 */ }
@@ -286,7 +287,7 @@ export function storageRoutes(
         if (!meta && rawSql) {
             try {
                 const rows = await rawSql(
-                    `SELECT storage_id, name, size, type FROM files WHERE storage_id = $1 LIMIT 1`,
+                    `SELECT storage_id, name, size, type FROM _system_files WHERE storage_id = $1 LIMIT 1`,
                     [id]
                 );
                 if (rows.length > 0) {

package/src/v.ts

@@ -135,11 +135,15 @@ export function parseArgs(schema: any, args: any): any {
 
     // Shorthand object — e.g. { id: v.number(), title: v.optional(v.string()) }
     if (typeof schema === "object" && schema !== null) {
+        // Empty schema {} → passthrough all args (e.g. FormData with file field)
+        const schemaKeys = Object.keys(schema);
+        if (schemaKeys.length === 0) return args;
+
         if (typeof args !== "object" || args === null) {
             throw new GencowValidationError("Expected an object for arguments");
         }
         const result: any = {};
-        for (const key in schema) {
+        for (const key of schemaKeys) {
             const validator = schema[key];
             if (validator && typeof validator.parse === "function") {
                 try {