@gencow/core 0.1.17 → 0.1.18

package/dist/crud.js

@@ -280,7 +280,6 @@ export function crud(table, options) {
     // ── create ────────────────────────────────────
     const createDef = !enabledMethods.has('create') ? undefined : mutation(`${prefix}.create`, {
         public: isPublic,
-        invalidates: [],
         handler: async (ctx, args) => {
             const user = isPublic ? null : ctx.auth.requireAuth();
             let insertData = { ...args };
@@ -304,7 +303,6 @@ export function crud(table, options) {
     // ── update ────────────────────────────────────
     const updateDef = !enabledMethods.has('update') ? undefined : mutation(`${prefix}.update`, {
         public: isPublic,
-        invalidates: [],
         handler: async (ctx, args) => {
             if (!isPublic)
                 ctx.auth.requireAuth();
@@ -338,7 +336,6 @@ export function crud(table, options) {
     // ── remove ────────────────────────────────────
     const removeDef = !enabledMethods.has('remove') ? undefined : mutation(`${prefix}.remove`, {
         public: isPublic,
-        invalidates: [],
         handler: async (ctx, args) => {
             if (!isPublic)
                 ctx.auth.requireAuth();

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * All with Convex-compatible DX patterns.
  */
 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/dist/index.js

@@ -4,7 +4,7 @@
  * Provides: query, mutation, storage, scheduler, auth
  * All with Convex-compatible DX patterns.
  */
-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 { createScheduler, getSchedulerInfo } from "./scheduler";
 export { v, parseArgs, GencowValidationError } from "./v";
 export { withRetry } from "./retry";

package/dist/reactive.d.ts

@@ -19,6 +19,9 @@ export interface AuthCtx {
  */
 export interface RealtimeCtx {
     /**
+     * 특정 queryKey를 구독 중인 클라이언트에 데이터를 즉시 push합니다.
+     * 초고빈도 mutation (채팅 등)에서 query re-run 비용을 회피할 때 사용.
+     *
      * @param queryKey - 업데이트할 쿼리 키 (예: "tasks.list")
      * @param data     - push할 데이터 (해당 query 결과와 동일한 타입)
      *
@@ -27,6 +30,23 @@ 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;
 }
 /**
  * 사용자 함수(query/mutation)에 주입되는 컨텍스트.
@@ -128,7 +148,6 @@ export interface QueryDef<TSchema = any, TReturn = any> {
     _return?: TReturn;
 }
 export interface MutationDef<TSchema = any, TReturn = any> {
-    invalidates: string[];
     handler: MutationHandler<InferArgs<TSchema>, TReturn>;
     argsSchema?: TSchema;
     /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
@@ -170,7 +189,6 @@ export declare function query<TSchema = any, TReturn = any>(key: string, handler
  * ```typescript
  * // ✅ 권장: query와 동일한 (name, def) 패턴
  * mutation("tasks.create", {
- *     invalidates: [],
  *     args: { title: v.string() },
  *     handler: async (ctx, args) => { ... },
  * });
@@ -178,19 +196,21 @@ export declare function query<TSchema = any, TReturn = any>(key: string, handler
  * // ✅ 객체 스타일 (하위 호환)
  * 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 declare function mutation<TSchema = any, TReturn = any>(nameOrInvalidatesOrDef: string | string[] | {
     name?: string;
     args?: TSchema;
     public?: boolean;
-    invalidates: string[];
+    invalidates?: string[];
     handler: MutationHandler<InferArgs<TSchema>, TReturn>;
 }, handlerOrDef?: MutationHandler<InferArgs<TSchema>, TReturn> | {
     invalidates?: string[];
@@ -235,14 +255,10 @@ export declare function unsubscribe(ws: WSContext): void;
 /** Register a raw WS connection without any query subscription (e.g. admin dashboard) */
 export declare function registerClient(ws: WSContext): void;
 export declare function deregisterClient(ws: WSContext): void;
-/**
- * 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하여 불필요한 전송을 방지합니다.
@@ -252,6 +268,8 @@ export declare function deregisterClient(ws: WSContext): void;
  * @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 declare function buildRealtimeCtx(options?: {
     httpCallback?: (event: {
@@ -259,18 +277,13 @@ export declare function buildRealtimeCtx(options?: {
         queryKey: string;
         data: unknown;
     }) => void;
-}): RealtimeCtx;
-/**
- * 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 declare function invalidateQueries(queryKeys: string[], ctx: GencowCtx, httpInvalidateCallback?: (queryKeys: string[]) => void): Promise<void>;
+    queryMap?: Map<string, QueryDef<any, any>>;
+    buildCtxForRefresh?: () => GencowCtx;
+}): RealtimeCtx & {
+    _hasEmitted: boolean;
+    _pendingRefresh: string[];
+    _flushRefresh: () => Promise<void>;
+};
 export declare function handleWsMessage(ws: WSContext, raw: string | ArrayBuffer): void;
 export declare function getQueryHandler(key: string): QueryHandler | undefined;
 export declare function getQueryDef(key: string): QueryDef | undefined;

package/dist/reactive.js

@@ -45,7 +45,6 @@ let mutationCounter = 0;
  * ```typescript
  * // ✅ 권장: query와 동일한 (name, def) 패턴
  * mutation("tasks.create", {
- *     invalidates: [],
  *     args: { title: v.string() },
  *     handler: async (ctx, args) => { ... },
  * });
@@ -53,38 +52,36 @@ 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(nameOrInvalidatesOrDef, handlerOrDef, name) {
-    let invalidates;
     let argsSchema;
     let actualHandler;
     let mutName;
     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;
-        invalidates = def.invalidates || [];
         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;
         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;
@@ -97,7 +94,6 @@ export function mutation(nameOrInvalidatesOrDef, handlerOrDef, name) {
     }
     const def = {
         name: mutName,
-        invalidates,
         handler: actualHandler,
         argsSchema,
         isPublic,
@@ -168,14 +164,10 @@ export function deregisterClient(ws) {
         clients.delete(ws);
     }
 }
-/**
- * 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하여 불필요한 전송을 방지합니다.
@@ -185,11 +177,16 @@ export function deregisterClient(ws) {
  * @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) {
     const pendingEmits = new Map();
+    const _pendingRefresh = [];
+    let _hasEmitted = false;
     return {
         emit(queryKey, data) {
+            _hasEmitted = true;
             // 기존 pending timer가 있으면 취소 (debounce)
             const existing = pendingEmits.get(queryKey);
             if (existing)
@@ -220,38 +217,61 @@ export function buildRealtimeCtx(options) {
                 }
             }, 50); // 50ms batch window
             pendingEmits.set(queryKey, { data, timer });
-        }
+        },
+        refresh(queryKey) {
+            _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 스코프)
+                    const refreshCtx = options?.buildCtxForRefresh?.() ?? {};
+                    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;
+        },
     };
 }
-/**
- * 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, ctx, httpInvalidateCallback) {
-    if (queryKeys.length === 0)
-        return; // emit() 방식에서는 no-op
-    // BaaS 모드: Platform WS Gateway에 HTTP callback
-    if (httpInvalidateCallback) {
-        httpInvalidateCallback(queryKeys);
-        return;
-    }
-    // 로컬 dev: WS 직접 broadcast (기존 동작)
-    const invalidateMsg = JSON.stringify({ type: "invalidate", queries: queryKeys });
-    for (const ws of connectedClients) {
-        try {
-            ws.send(invalidateMsg);
-        }
-        catch {
-            connectedClients.delete(ws);
-        }
-    }
-}
 // ─── WebSocket message handler ──────────────────────────
 export function handleWsMessage(ws, raw) {
     try {

package/dist/scoped-db.d.ts

@@ -0,0 +1,34 @@
+/**
+ * packages/core/src/scoped-db.ts
+ *
+ * Creates a scoped (Proxy-wrapped) Drizzle DB instance that auto-injects
+ * schema-level access control filters from gencowTable() metadata.
+ *
+ * Key behaviors:
+ *   - .select().from(gencowTable) → auto-inject filter into WHERE
+ *   - .insert(table) / .update(table) / .delete(table) → inject filter for writes
+ *   - .leftJoin(table) / .innerJoin(table) → detect and inject filter
+ *   - .execute() → blocked (throws Error)
+ *   - .query.tableName.findMany() → inject filter into relational queries
+ *
+ * Run tests: bun test packages/core/src/__tests__/scoped-db.test.ts
+ */
+import type { GencowCtx } from "./reactive";
+/**
+ * Wrap a Drizzle DB instance with access control Proxy.
+ *
+ * @param db  - Raw Drizzle DB instance
+ * @param ctx - GencowCtx (provides auth for filter evaluation)
+ * @returns Proxy-wrapped DB with auto-filter injection
+ */
+export declare function createScopedDb(db: any, ctx: GencowCtx): any;
+/**
+ * Apply field-level access control to query results.
+ * Nullifies fields that the current user is not authorized to read.
+ *
+ * @param result - Query result (array or single object)
+ * @param table  - The gencowTable used in the query
+ * @param ctx    - GencowCtx for auth checks
+ * @returns Filtered result with unauthorized fields set to null
+ */
+export declare function applyFieldAccess(result: any, table: any, ctx: GencowCtx): any;