@gencow/core 0.1.15 → 0.1.16

package/dist/reactive.d.ts

@@ -48,7 +48,7 @@ export interface AIResult {
     model: string;
 }
 export interface AIContext {
-    /** AI 텍스트 생성 — ctx.ai.chat({ model, messages }) */
+    /** AI 텍스트 생성 */
     chat: (opts: {
         model?: string;
         messages: AIMessage[];
@@ -61,9 +61,9 @@ export interface AIContext {
             type: string;
         };
     }) => Promise<AIResult>;
-    /** 텍스트 임베딩 (단일) — ctx.ai.embed("검색 텍스트") */
+    /** 텍스트 임베딩 (단일) */
     embed: (text: string) => Promise<number[]>;
-    /** 배치 임베딩 — ctx.ai.embedMany(["텍스트1", "텍스트2"]) */
+    /** 배치 임베딩 */
     embedMany: (texts: string[]) => Promise<number[][]>;
 }
 export interface GencowCtx {
@@ -81,7 +81,7 @@ export interface GencowCtx {
     realtime: RealtimeCtx;
     /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
     retry: <T>(fn: () => Promise<T>, options?: import("./retry").RetryOptions) => Promise<T>;
-    /** AI 헬퍼 — ctx.ai.chat({ model, messages }) — 로컬: 직접 호출, BaaS: Control Plane 프록시 */
+    /** AI 헬퍼 */
     ai?: AIContext;
 }
 type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
@@ -248,8 +248,18 @@ export declare function deregisterClient(ws: WSContext): void;
  * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
  *
  * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
+ *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
+ *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
  */
-export declare function buildRealtimeCtx(): RealtimeCtx;
+export declare function buildRealtimeCtx(options?: {
+    httpCallback?: (event: {
+        type: "emit";
+        queryKey: string;
+        data: unknown;
+    }) => void;
+}): RealtimeCtx;
 /**
  * mutation이 끝난 후 호출되는 legacy fallback.
  * `ctx.realtime.emit()`을 사용하는 새 mutation에서는 빈 배열([])을 전달하면 됩니다.
@@ -258,8 +268,9 @@ export declare function buildRealtimeCtx(): RealtimeCtx;
  * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
  *
  * @deprecated ctx.realtime.emit() 사용 권장
+ * @param httpInvalidateCallback  BaaS 모드: Platform WS Gateway에 HTTP로 invalidation 전달.
  */
-export declare function invalidateQueries(queryKeys: string[], ctx: GencowCtx): Promise<void>;
+export declare function invalidateQueries(queryKeys: string[], ctx: GencowCtx, httpInvalidateCallback?: (queryKeys: string[]) => void): 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

@@ -181,8 +181,12 @@ export function deregisterClient(ws) {
  * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
  *
  * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
+ *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
+ *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
  */
-export function buildRealtimeCtx() {
+export function buildRealtimeCtx(options) {
     const pendingEmits = new Map();
     return {
         emit(queryKey, data) {
@@ -192,6 +196,12 @@ export function buildRealtimeCtx() {
                 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;
@@ -221,11 +231,17 @@ export function buildRealtimeCtx() {
  * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
  *
  * @deprecated ctx.realtime.emit() 사용 권장
+ * @param httpInvalidateCallback  BaaS 모드: Platform WS Gateway에 HTTP로 invalidation 전달.
  */
-export async function invalidateQueries(queryKeys, ctx) {
+export async function invalidateQueries(queryKeys, ctx, httpInvalidateCallback) {
     if (queryKeys.length === 0)
         return; // emit() 방식에서는 no-op
-    // invalidate 신호만 broadcast (re-fetch는 클라이언트 결정에 맡김)
+    // 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gencow/core",
-    "version": "0.1.15",
+    "version": "0.1.16",
     "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
     "type": "module",
     "main": "dist/index.js",

package/src/reactive.ts

@@ -54,7 +54,7 @@ export interface AIResult {
 }
 
 export interface AIContext {
-    /** AI 텍스트 생성 — ctx.ai.chat({ model, messages }) */
+    /** AI 텍스트 생성 */
     chat: (opts: {
         model?: string;
         messages: AIMessage[];
@@ -65,9 +65,9 @@ export interface AIContext {
         /** Response format — e.g. { type: "json_object" } for JSON mode */
         responseFormat?: { type: string };
     }) => Promise<AIResult>;
-    /** 텍스트 임베딩 (단일) — ctx.ai.embed("검색 텍스트") */
+    /** 텍스트 임베딩 (단일) */
     embed: (text: string) => Promise<number[]>;
-    /** 배치 임베딩 — ctx.ai.embedMany(["텍스트1", "텍스트2"]) */
+    /** 배치 임베딩 */
     embedMany: (texts: string[]) => Promise<number[][]>;
 }
 
@@ -86,7 +86,7 @@ export interface GencowCtx {
     realtime: RealtimeCtx;
     /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
     retry: <T>(fn: () => Promise<T>, options?: import("./retry").RetryOptions) => Promise<T>;
-    /** AI 헬퍼 — ctx.ai.chat({ model, messages }) — 로컬: 직접 호출, BaaS: Control Plane 프록시 */
+    /** AI 헬퍼 */
     ai?: AIContext;
 }
 
@@ -392,8 +392,14 @@ export function deregisterClient(ws: WSContext) {
  * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
  *
  * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
+ *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
+ *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
  */
-export function buildRealtimeCtx(): RealtimeCtx {
+export function buildRealtimeCtx(options?: {
+    httpCallback?: (event: { type: "emit"; queryKey: string; data: unknown }) => void;
+}): RealtimeCtx {
     const pendingEmits = new Map<string, { data: unknown; timer: ReturnType<typeof setTimeout> }>();
 
     return {
@@ -404,6 +410,14 @@ export function buildRealtimeCtx(): RealtimeCtx {
 
             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;
 
@@ -430,14 +444,22 @@ export function buildRealtimeCtx(): RealtimeCtx {
  * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
  *
  * @deprecated ctx.realtime.emit() 사용 권장
+ * @param httpInvalidateCallback  BaaS 모드: Platform WS Gateway에 HTTP로 invalidation 전달.
  */
 export async function invalidateQueries(
     queryKeys: string[],
-    ctx: GencowCtx
+    ctx: GencowCtx,
+    httpInvalidateCallback?: (queryKeys: string[]) => void,
 ): Promise<void> {
     if (queryKeys.length === 0) return; // emit() 방식에서는 no-op
 
-    // invalidate 신호만 broadcast (re-fetch는 클라이언트 결정에 맡김)
+    // 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); }