@gencow/core 0.1.28 → 0.1.29

package/dist/reactive-mutation-types.d.ts

@@ -0,0 +1,11 @@
+import type { InferArgs } from "./v.js";
+import type { GencowCtx } from "./context.js";
+export type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<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;
+}

package/dist/reactive-mutation-types.js

@@ -0,0 +1 @@
+export {};

package/dist/reactive-mutation.d.ts

@@ -0,0 +1,51 @@
+import { type InferArgs } from "./v.js";
+import type { MutationDef, MutationHandler } from "./reactive-mutation-types.js";
+declare global {
+    var __gencow_mutationRegistry: (MutationDef<any, any> & {
+        name: string;
+    })[];
+}
+export declare const mutationRegistry: (MutationDef<any, any> & {
+    name: string;
+})[];
+/**
+ * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
+ *
+ * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
+ *
+ * @example
+ * ```typescript
+ * // ✅ 권장: query와 동일한 (name, def) 패턴
+ * mutation("tasks.create", {
+ *     args: { title: v.string() },
+ *     handler: async (ctx, args) => { ... },
+ * });
+ *
+ * // ✅ 객체 스타일 (하위 호환)
+ * mutation({
+ *     name: "tasks.create",
+ *     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[];
+    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>;
+export declare function getRegisteredMutations(): (MutationDef & {
+    name: string;
+})[];

package/dist/reactive-mutation.js

@@ -0,0 +1,75 @@
+if (!globalThis.__gencow_mutationRegistry)
+    globalThis.__gencow_mutationRegistry = [];
+export const mutationRegistry = globalThis.__gencow_mutationRegistry;
+let mutationCounter = 0;
+/**
+ * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
+ *
+ * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
+ *
+ * @example
+ * ```typescript
+ * // ✅ 권장: query와 동일한 (name, def) 패턴
+ * mutation("tasks.create", {
+ *     args: { title: v.string() },
+ *     handler: async (ctx, args) => { ... },
+ * });
+ *
+ * // ✅ 객체 스타일 (하위 호환)
+ * mutation({
+ *     name: "tasks.create",
+ *     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 argsSchema;
+    let actualHandler;
+    let mutName;
+    let isPublic = false;
+    if (typeof nameOrInvalidatesOrDef === "string") {
+        // New primary style: mutation("name", { args?, public?, handler })
+        mutName = nameOrInvalidatesOrDef;
+        const def = handlerOrDef;
+        actualHandler = def.handler;
+        argsSchema = def.args;
+        isPublic = def.public === true;
+    }
+    else if (Array.isArray(nameOrInvalidatesOrDef)) {
+        // Legacy style: mutation([...], handler, "name") — invalidates ignored
+        actualHandler = handlerOrDef;
+        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 = {
+        name: mutName,
+        handler: actualHandler,
+        argsSchema,
+        isPublic,
+    };
+    mutationRegistry.push(def);
+    return def;
+}
+export function getRegisteredMutations() {
+    return [...mutationRegistry];
+}

package/dist/reactive-query-types.d.ts

@@ -0,0 +1,12 @@
+import type { InferArgs } from "./v.js";
+import type { GencowCtx } from "./context.js";
+export type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+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;
+}

package/dist/reactive-query-types.js

@@ -0,0 +1 @@
+export {};

package/dist/reactive-query.d.ts

@@ -0,0 +1,14 @@
+import { type InferArgs } from "./v.js";
+import type { QueryDef, QueryHandler } from "./reactive-query-types.js";
+declare global {
+    var __gencow_queryRegistry: Map<string, QueryDef<any, any>>;
+}
+export declare const queryRegistry: Map<string, QueryDef<any, any>>;
+export declare function query<TSchema = any, TReturn = any>(key: string, handlerOrDef: QueryHandler<InferArgs<TSchema>, TReturn> | {
+    args?: TSchema;
+    public?: boolean;
+    handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+}): QueryDef<TSchema, TReturn>;
+export declare function getQueryHandler(key: string): QueryHandler | undefined;
+export declare function getQueryDef(key: string): QueryDef | undefined;
+export declare function getRegisteredQueries(): string[];

package/dist/reactive-query.js

@@ -0,0 +1,28 @@
+if (!globalThis.__gencow_queryRegistry)
+    globalThis.__gencow_queryRegistry = new Map();
+export const queryRegistry = globalThis.__gencow_queryRegistry;
+export function query(key, handlerOrDef) {
+    let handler;
+    let argsSchema;
+    let isPublic = false;
+    if (typeof handlerOrDef === "function") {
+        handler = handlerOrDef;
+    }
+    else {
+        handler = handlerOrDef.handler;
+        argsSchema = handlerOrDef.args;
+        isPublic = handlerOrDef.public === true;
+    }
+    const def = { key, handler, argsSchema, isPublic };
+    queryRegistry.set(key, def);
+    return def;
+}
+export function getQueryHandler(key) {
+    return queryRegistry.get(key)?.handler;
+}
+export function getQueryDef(key) {
+    return queryRegistry.get(key);
+}
+export function getRegisteredQueries() {
+    return Array.from(queryRegistry.keys());
+}

package/dist/reactive-realtime.d.ts

@@ -0,0 +1,48 @@
+import type { WSContext } from "hono/ws";
+import type { GencowCtx, RealtimeCtx, RealtimeNotifyEvent } from "./context.js";
+import type { QueryDef } from "./reactive-query-types.js";
+declare global {
+    var __gencow_subscribers: Map<string, Set<WSContext>>;
+    var __gencow_connectedClients: Set<WSContext>;
+}
+export declare const subscribers: Map<string, Set<WSContext<unknown>>>;
+/**
+ * Every WebSocket client that ever establishes a connection is tracked here.
+ * This allows broadcasting invalidation events to clients that never subscribed
+ * to a specific query (e.g. the admin dashboard's raw WebSocket connection).
+ */
+export declare const connectedClients: Set<WSContext<unknown>>;
+/** Stable subscription key for WebSocket / invalidate fanout (also used by crud for query keys). */
+export declare function buildQuerySubscriptionKey(queryKey: string, args?: unknown): string;
+export declare function subscriptionKeyMatchesQueryKey(subscriptionKey: string, queryKey: string): boolean;
+export declare function subscribe(queryKey: string, ws: WSContext): void;
+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;
+/**
+ * mutation 실행 시점에 생성되는 RealtimeCtx.
+ * emit(): 데이터를 직접 push (초고빈도 mutation용).
+ * refresh(): queryKey를 pending 큐에 추가, mutation 완료 후 서버가 query re-run하여 push.
+ *
+ * 💡 Batching: 같은 queryKey에 대한 emit이 50ms 내에 여러 번 호출되면
+ * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
+ *
+ * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @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: RealtimeNotifyEvent) => 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;

package/dist/reactive-realtime.js

@@ -0,0 +1,236 @@
+import { queryRegistry } from "./reactive-query.js";
+if (!globalThis.__gencow_subscribers)
+    globalThis.__gencow_subscribers = new Map();
+if (!globalThis.__gencow_connectedClients)
+    globalThis.__gencow_connectedClients = new Set();
+export const subscribers = globalThis.__gencow_subscribers;
+/**
+ * Every WebSocket client that ever establishes a connection is tracked here.
+ * This allows broadcasting invalidation events to clients that never subscribed
+ * to a specific query (e.g. the admin dashboard's raw WebSocket connection).
+ */
+export const connectedClients = globalThis.__gencow_connectedClients;
+const SUBSCRIPTION_KEY_SEPARATOR = "::";
+function normalizeForStableJson(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map((item) => normalizeForStableJson(item));
+    if (typeof value === "object") {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            const normalized = normalizeForStableJson(source[key]);
+            if (normalized !== undefined)
+                sorted[key] = normalized;
+        }
+        return sorted;
+    }
+    return value;
+}
+function isEmptyPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0;
+}
+/** Stable subscription key for WebSocket / invalidate fanout (also used by crud for query keys). */
+export function buildQuerySubscriptionKey(queryKey, args) {
+    const normalized = normalizeForStableJson(args);
+    if (normalized === undefined || isEmptyPlainObject(normalized))
+        return queryKey;
+    return `${queryKey}${SUBSCRIPTION_KEY_SEPARATOR}${JSON.stringify(normalized)}`;
+}
+export function subscriptionKeyMatchesQueryKey(subscriptionKey, queryKey) {
+    return subscriptionKey === queryKey || subscriptionKey.startsWith(`${queryKey}${SUBSCRIPTION_KEY_SEPARATOR}`);
+}
+export function subscribe(queryKey, ws) {
+    connectedClients.add(ws);
+    if (!subscribers.has(queryKey)) {
+        subscribers.set(queryKey, new Set());
+    }
+    subscribers.get(queryKey).add(ws);
+}
+export function unsubscribe(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) {
+    connectedClients.add(ws);
+}
+export function deregisterClient(ws) {
+    connectedClients.delete(ws);
+    for (const clients of subscribers.values()) {
+        clients.delete(ws);
+    }
+}
+function sendInvalidateToLocalSubscribers(queryKeys) {
+    const targets = new Map();
+    for (const queryKey of queryKeys) {
+        for (const [subscriptionKey, clients] of subscribers) {
+            if (!subscriptionKeyMatchesQueryKey(subscriptionKey, queryKey))
+                continue;
+            for (const ws of clients) {
+                if (!targets.has(ws))
+                    targets.set(ws, new Set());
+                targets.get(ws).add(subscriptionKey);
+            }
+        }
+    }
+    for (const [ws, keys] of targets) {
+        try {
+            ws.send(JSON.stringify({ type: "invalidate", queries: [...keys] }));
+        }
+        catch {
+            deregisterClient(ws);
+        }
+    }
+}
+/**
+ * mutation 실행 시점에 생성되는 RealtimeCtx.
+ * emit(): 데이터를 직접 push (초고빈도 mutation용).
+ * refresh(): queryKey를 pending 큐에 추가, mutation 완료 후 서버가 query re-run하여 push.
+ *
+ * 💡 Batching: 같은 queryKey에 대한 emit이 50ms 내에 여러 번 호출되면
+ * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
+ *
+ * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @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)
+                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 });
+        },
+        invalidate(queryKey) {
+            _hasEmitted = true;
+            const queryKeys = Array.isArray(queryKey) ? [...new Set(queryKey)] : [queryKey];
+            if (options?.httpCallback) {
+                options.httpCallback({ type: "invalidate", queryKeys });
+                return;
+            }
+            sendInvalidateToLocalSubscribers(queryKeys);
+        },
+        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 스코프)
+                    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?.() ?? {};
+                    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;
+        },
+    };
+}
+export function handleWsMessage(ws, raw) {
+    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 }));
+        }
+        if (msg.type === "unsubscribe" && msg.query) {
+            const clients = subscribers.get(msg.query);
+            if (clients)
+                clients.delete(ws);
+        }
+    }
+    catch {
+        // ignore malformed messages
+    }
+}

package/dist/reactive.d.ts

@@ -33,6 +33,11 @@ export interface RealtimeCtx {
      *   ctx.realtime.emit("tasks.list", freshList);
      */
     emit(queryKey: string, data: unknown): void;
+    /**
+     * 특정 queryKey 구독자에게 재조회 신호만 보냅니다.
+     * private/RLS query처럼 서버가 안전하게 full payload를 만들 수 없는 경우 기본값입니다.
+     */
+    invalidate(queryKey: string | string[]): void;
     /**
      * 수동 mutation에서 리얼타임 업데이트의 기본 권장 방식.
      * mutation handler 완료 후 서버가 해당 query를 re-run하여 결과를 push합니다.
@@ -51,6 +56,14 @@ export interface RealtimeCtx {
      */
     refresh(queryKey: string): void;
 }
+export type RealtimeNotifyEvent = {
+    type: "emit";
+    queryKey: string;
+    data: unknown;
+} | {
+    type: "invalidate";
+    queryKeys: string[];
+};
 /**
  * 사용자 함수(query/mutation)에 주입되는 컨텍스트.
  * Convex의 ctx 패턴과 동일하게, 이 객체를 통해서만 DB/Storage/Auth에 접근 가능.
@@ -188,6 +201,8 @@ declare global {
     var __gencow_connectedClients: Set<WSContext>;
     var __gencow_httpActionRegistry: HttpActionDef[];
 }
+export declare function buildQuerySubscriptionKey(queryKey: string, args?: unknown): string;
+export declare function subscriptionKeyMatchesQueryKey(subscriptionKey: string, queryKey: string): boolean;
 export declare function query<TSchema = any, TReturn = any>(key: string, handlerOrDef: QueryHandler<InferArgs<TSchema>, TReturn> | {
     args?: TSchema;
     public?: boolean;
@@ -285,11 +300,7 @@ export declare function deregisterClient(ws: WSContext): void;
  * @param options.buildCtxForRefresh  refresh 시 query handler에 전달할 ctx 생성 함수.
  */
 export declare function buildRealtimeCtx(options?: {
-    httpCallback?: (event: {
-        type: "emit";
-        queryKey: string;
-        data: unknown;
-    }) => void;
+    httpCallback?: (event: RealtimeNotifyEvent) => void;
     queryMap?: Map<string, QueryDef<any, any>>;
     buildCtxForRefresh?: () => GencowCtx;
 }): RealtimeCtx & {

package/dist/reactive.js

@@ -18,6 +18,40 @@ const subscribers = globalThis.__gencow_subscribers;
  * to a specific query (e.g. the admin dashboard's raw WebSocket connection).
  */
 const connectedClients = globalThis.__gencow_connectedClients;
+const SUBSCRIPTION_KEY_SEPARATOR = "::";
+function normalizeForStableJson(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map((item) => normalizeForStableJson(item));
+    if (typeof value === "object") {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            const normalized = normalizeForStableJson(source[key]);
+            if (normalized !== undefined)
+                sorted[key] = normalized;
+        }
+        return sorted;
+    }
+    return value;
+}
+function isEmptyPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0;
+}
+export function buildQuerySubscriptionKey(queryKey, args) {
+    const normalized = normalizeForStableJson(args);
+    if (normalized === undefined || isEmptyPlainObject(normalized))
+        return queryKey;
+    return `${queryKey}${SUBSCRIPTION_KEY_SEPARATOR}${JSON.stringify(normalized)}`;
+}
+export function subscriptionKeyMatchesQueryKey(subscriptionKey, queryKey) {
+    return subscriptionKey === queryKey || subscriptionKey.startsWith(`${queryKey}${SUBSCRIPTION_KEY_SEPARATOR}`);
+}
 // ─── Public API (Convex-style) ──────────────────────────
 export function query(key, handlerOrDef) {
     let handler;
@@ -167,6 +201,28 @@ export function deregisterClient(ws) {
         clients.delete(ws);
     }
 }
+function sendInvalidateToLocalSubscribers(queryKeys) {
+    const targets = new Map();
+    for (const queryKey of queryKeys) {
+        for (const [subscriptionKey, clients] of subscribers) {
+            if (!subscriptionKeyMatchesQueryKey(subscriptionKey, queryKey))
+                continue;
+            for (const ws of clients) {
+                if (!targets.has(ws))
+                    targets.set(ws, new Set());
+                targets.get(ws).add(subscriptionKey);
+            }
+        }
+    }
+    for (const [ws, keys] of targets) {
+        try {
+            ws.send(JSON.stringify({ type: "invalidate", queries: [...keys] }));
+        }
+        catch {
+            deregisterClient(ws);
+        }
+    }
+}
 /**
  * mutation 실행 시점에 생성되는 RealtimeCtx.
  * emit(): 데이터를 직접 push (초고빈도 mutation용).
@@ -221,6 +277,15 @@ export function buildRealtimeCtx(options) {
             }, 50); // 50ms batch window
             pendingEmits.set(queryKey, { data, timer });
         },
+        invalidate(queryKey) {
+            _hasEmitted = true;
+            const queryKeys = Array.isArray(queryKey) ? [...new Set(queryKey)] : [queryKey];
+            if (options?.httpCallback) {
+                options.httpCallback({ type: "invalidate", queryKeys });
+                return;
+            }
+            sendInvalidateToLocalSubscribers(queryKeys);
+        },
         refresh(queryKey) {
             _hasEmitted = true; // 경고 억제
             if (!_pendingRefresh.includes(queryKey)) {

package/dist/runtime-env-policy.js

@@ -36,7 +36,7 @@ const RESERVED_TENANT_RUNTIME_ENV_KEYS = new Set([
     "MIMALLOC_PURGE_DELAY",
     "NODE_PATH",
 ]);
-const RESERVED_TENANT_RUNTIME_ENV_PREFIXES = ["__GENCOW_", "GENCOW_DOCUMENT_", "GENCOW_WARM_"];
+const RESERVED_TENANT_RUNTIME_ENV_PREFIXES = ["__GENCOW_", "GENCOW_DOCUMENT_", "GENCOW_TEMPLATE_", "GENCOW_WARM_"];
 export function isReservedTenantRuntimeEnvKey(key) {
     const normalized = key.trim();
     return (RESERVED_TENANT_RUNTIME_ENV_KEYS.has(normalized) ||

package/dist/server.d.ts

@@ -6,5 +6,5 @@
  * bundled into user functions which run in Firecracker.
  */
 export { createStorage, storageRoutes } from "./storage.js";
-export type { StorageImageTierConfig, StoredFile } from "./storage.js";
+export type { StorageImageTierConfig, StorageImageTransformMetric, StorageMeteringOptions, StoredFile, } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";

package/dist/storage-metering.d.ts

@@ -0,0 +1,13 @@
+export interface StorageImageTransformMetric {
+    transformCount: number;
+    sourceBytes: number;
+    outputBytes: number;
+    format: string;
+    autoWebp: boolean;
+}
+export interface StorageMeteringOptions {
+    onImageTransform?: (metric: StorageImageTransformMetric) => void | Promise<void>;
+}
+export declare function recordStorageImageTransform(options: StorageMeteringOptions | undefined, cachePath: string, metric: Omit<StorageImageTransformMetric, "transformCount" | "outputBytes">): Promise<{
+    size: number;
+}>;

package/dist/storage-metering.js

@@ -0,0 +1,18 @@
+import * as fs from "fs/promises";
+export async function recordStorageImageTransform(options, cachePath, metric) {
+    const stats = await fs.stat(cachePath);
+    if (!options?.onImageTransform)
+        return stats;
+    try {
+        await options.onImageTransform({
+            ...metric,
+            transformCount: 1,
+            outputBytes: stats.size,
+        });
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.warn(`[storage] image transform metering failed: ${msg.slice(0, 120)}`);
+    }
+    return stats;
+}