@gencow/core 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,56 @@
+import type { Context, Next } from "hono";
+interface User {
+    id: string;
+    email: string;
+    name?: string;
+}
+interface AuthConfig {
+    jwtSecret: string;
+}
+/**
+ * Auth middleware that injects `c.get('auth')` into context
+ *
+ * @example
+ * app.use('*', authMiddleware({ jwtSecret: 'secret' }));
+ *
+ * // In query/mutation:
+ * const user = c.get('auth').requireAuth();
+ */
+export declare function authMiddleware(config: AuthConfig): (c: Context, next: Next) => Promise<void>;
+export declare function authRoutes(config: AuthConfig): {
+    /** POST /auth/signup — 회원가입 */
+    signup(c: Context): Promise<(Response & import("hono").TypedResponse<{
+        error: string;
+    }, 400, "json">) | (Response & import("hono").TypedResponse<{
+        error: string;
+    }, 409, "json">) | (Response & import("hono").TypedResponse<{
+        token: string;
+        user: {
+            id: `${string}-${string}-${string}-${string}-${string}`;
+            email: any;
+            name: any;
+        };
+    }, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+    /** POST /auth/login — 로그인 */
+    login(c: Context): Promise<(Response & import("hono").TypedResponse<{
+        error: string;
+    }, 401, "json">) | (Response & import("hono").TypedResponse<{
+        token: string;
+        user: {
+            id: string;
+            email: string;
+            name: string | undefined;
+        };
+    }, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+    /** GET /auth/me — 현재 유저 정보 */
+    me(c: Context): Promise<Response & import("hono").TypedResponse<{
+        id: string;
+        email: string;
+        name?: string | undefined;
+    }, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+};
+/** Get all registered users (for admin dashboard) */
+export declare function getUsers(): (User & {
+    createdAt: string;
+})[];
+export {};

package/dist/auth.js

@@ -0,0 +1,107 @@
+import { HTTPException } from "hono/http-exception";
+import { sign, verify } from "hono/utils/jwt/jwt";
+// ─── In-memory user store (POC용, 프로덕션에서는 Drizzle 테이블 사용) ──
+const users = new Map();
+// ─── Simple password hashing (POC용) ────────────────────
+async function hashPassword(password) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(password);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(hash))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// ─── Auth middleware — Convex ctx.auth 패턴 재현 ─────────
+/**
+ * Auth middleware that injects `c.get('auth')` into context
+ *
+ * @example
+ * app.use('*', authMiddleware({ jwtSecret: 'secret' }));
+ *
+ * // In query/mutation:
+ * const user = c.get('auth').requireAuth();
+ */
+export function authMiddleware(config) {
+    return async (c, next) => {
+        let currentUser = null;
+        // Extract JWT from Authorization header
+        const authHeader = c.req.header("Authorization");
+        if (authHeader?.startsWith("Bearer ")) {
+            const token = authHeader.slice(7);
+            try {
+                const payload = (await verify(token, config.jwtSecret, "HS256"));
+                currentUser = {
+                    id: payload.sub,
+                    email: payload.email,
+                    name: payload.name,
+                };
+            }
+            catch {
+                // Invalid token — continue as unauthenticated
+            }
+        }
+        const authContext = {
+            getUserIdentity: () => currentUser,
+            requireAuth: () => {
+                if (!currentUser) {
+                    throw new HTTPException(401, { message: "Authentication required" });
+                }
+                return currentUser;
+            },
+        };
+        c.set("auth", authContext);
+        await next();
+    };
+}
+// ─── Auth routes — 회원가입/로그인/프로필 ────────────────
+export function authRoutes(config) {
+    return {
+        /** POST /auth/signup — 회원가입 */
+        async signup(c) {
+            const { email, password, name } = await c.req.json();
+            if (!email || !password) {
+                return c.json({ error: "Email and password required" }, 400);
+            }
+            if (users.has(email)) {
+                return c.json({ error: "User already exists" }, 409);
+            }
+            const id = crypto.randomUUID();
+            const passwordHash = await hashPassword(password);
+            users.set(email, { id, email, name, passwordHash, createdAt: new Date().toISOString() });
+            const token = await sign({ sub: id, email, name, exp: Math.floor(Date.now() / 1000) + 86400 }, config.jwtSecret);
+            return c.json({ token, user: { id, email, name } });
+        },
+        /** POST /auth/login — 로그인 */
+        async login(c) {
+            const { email, password } = await c.req.json();
+            const user = users.get(email);
+            if (!user) {
+                return c.json({ error: "Invalid credentials" }, 401);
+            }
+            const hash = await hashPassword(password);
+            if (hash !== user.passwordHash) {
+                return c.json({ error: "Invalid credentials" }, 401);
+            }
+            const token = await sign({
+                sub: user.id,
+                email: user.email,
+                name: user.name,
+                exp: Math.floor(Date.now() / 1000) + 86400,
+            }, config.jwtSecret);
+            return c.json({
+                token,
+                user: { id: user.id, email: user.email, name: user.name },
+            });
+        },
+        /** GET /auth/me — 현재 유저 정보 */
+        async me(c) {
+            const auth = c.get("auth");
+            const user = auth.requireAuth();
+            return c.json(user);
+        },
+    };
+}
+/** Get all registered users (for admin dashboard) */
+export function getUsers() {
+    return Array.from(users.values()).map(({ passwordHash, ...user }) => user);
+}

package/dist/crons.d.ts

@@ -0,0 +1,70 @@
+/**
+ * packages/core/src/crons.ts
+ *
+ * 선언적 Cron Jobs — Convex cronJobs() 패턴
+ *
+ * gencow/crons.ts 파일에 선언하면 서버 시작 시 자동 등록됩니다.
+ *
+ * @example
+ * // gencow/crons.ts
+ * import { cronJobs } from "@gencow/core";
+ *
+ * const crons = cronJobs();
+ * crons.interval("sync-metrics", { minutes: 15 }, "metrics.collect");
+ * crons.daily("cleanup", { hour: 2 }, "admin.cleanup");
+ * crons.cron("custom", "0 * * * *", "hourly.task");
+ * export default crons;
+ */
+export interface CronJobDef {
+    /** 크론 잡 이름 */
+    name: string;
+    /** cron 표현식 (예: "0 2 * * *") */
+    pattern: string;
+    /** 실행할 액션 또는 핸들러 */
+    action: string | (() => Promise<void>);
+}
+export interface IntervalOptions {
+    /** 분 단위 */
+    minutes?: number;
+    /** 시간 단위 */
+    hours?: number;
+    /** 초 단위 */
+    seconds?: number;
+}
+export interface DailyOptions {
+    /** 실행 시각 (0-23, 로컬 시간) */
+    hour: number;
+    /** 분 (0-59, 기본 0) */
+    minute?: number;
+}
+export interface WeeklyOptions {
+    /** 요일 (0=일, 1=월, ..., 6=토) */
+    dayOfWeek: number;
+    /** 시각 (0-23) */
+    hour: number;
+    /** 분 (0-59, 기본 0) */
+    minute?: number;
+}
+export interface CronJobsBuilder {
+    /** 일정 간격으로 실행 */
+    interval(name: string, options: IntervalOptions, action: string | (() => Promise<void>)): CronJobsBuilder;
+    /** 매일 특정 시각에 실행 */
+    daily(name: string, options: DailyOptions, action: string | (() => Promise<void>)): CronJobsBuilder;
+    /** 매주 특정 요일/시각에 실행 */
+    weekly(name: string, options: WeeklyOptions, action: string | (() => Promise<void>)): CronJobsBuilder;
+    /** cron 표현식으로 직접 지정 */
+    cron(name: string, pattern: string, action: string | (() => Promise<void>)): CronJobsBuilder;
+    /** 등록된 크론 잡 목록 (서버 내부에서 사용) */
+    getJobs(): CronJobDef[];
+}
+/**
+ * 선언적 크론 잡 빌더
+ *
+ * @example
+ * const crons = cronJobs();
+ * crons.interval("sync", { minutes: 15 }, "metrics.collect");
+ * crons.daily("report", { hour: 9 }, "reports.generate");
+ * crons.cron("custom", "0 30 * * *", "custom.handler");
+ * export default crons;
+ */
+export declare function cronJobs(): CronJobsBuilder;

package/dist/crons.js

@@ -0,0 +1,72 @@
+/**
+ * packages/core/src/crons.ts
+ *
+ * 선언적 Cron Jobs — Convex cronJobs() 패턴
+ *
+ * gencow/crons.ts 파일에 선언하면 서버 시작 시 자동 등록됩니다.
+ *
+ * @example
+ * // gencow/crons.ts
+ * import { cronJobs } from "@gencow/core";
+ *
+ * const crons = cronJobs();
+ * crons.interval("sync-metrics", { minutes: 15 }, "metrics.collect");
+ * crons.daily("cleanup", { hour: 2 }, "admin.cleanup");
+ * crons.cron("custom", "0 * * * *", "hourly.task");
+ * export default crons;
+ */
+// ─── 빌더 구현 ──────────────────────────────────────────
+/**
+ * 선언적 크론 잡 빌더
+ *
+ * @example
+ * const crons = cronJobs();
+ * crons.interval("sync", { minutes: 15 }, "metrics.collect");
+ * crons.daily("report", { hour: 9 }, "reports.generate");
+ * crons.cron("custom", "0 30 * * *", "custom.handler");
+ * export default crons;
+ */
+export function cronJobs() {
+    const jobs = [];
+    const builder = {
+        interval(name, options, action) {
+            const pattern = intervalToPattern(options);
+            jobs.push({ name, pattern, action });
+            return builder;
+        },
+        daily(name, options, action) {
+            const minute = options.minute ?? 0;
+            const pattern = `${minute} ${options.hour} * * *`;
+            jobs.push({ name, pattern, action });
+            return builder;
+        },
+        weekly(name, options, action) {
+            const minute = options.minute ?? 0;
+            const pattern = `${minute} ${options.hour} * * ${options.dayOfWeek}`;
+            jobs.push({ name, pattern, action });
+            return builder;
+        },
+        cron(name, pattern, action) {
+            jobs.push({ name, pattern, action });
+            return builder;
+        },
+        getJobs() {
+            return [...jobs];
+        },
+    };
+    return builder;
+}
+// ─── 유틸리티 ───────────────────────────────────────────
+function intervalToPattern(options) {
+    if (options.seconds) {
+        // node-cron은 초 단위 지원: "*/N * * * * *"
+        return `*/${options.seconds} * * * * *`;
+    }
+    if (options.minutes) {
+        return `*/${options.minutes} * * * *`;
+    }
+    if (options.hours) {
+        return `0 */${options.hours} * * *`;
+    }
+    throw new Error("interval: minutes, hours, 또는 seconds 중 하나를 지정하세요");
+}

package/dist/db.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @deprecated — 레거시 싱글톤 DB 인스턴스.
+ * 새 코드에서는 ctx.db를 사용하세요.
+ * 서버의 createDatabase() (database.ts)가 실제 DB 연결을 관리합니다.
+ */
+import { PGlite } from "@electric-sql/pglite";
+/** @deprecated Use ctx.db instead */
+export declare function createDb(dataDir?: string): Promise<{
+    db: import("drizzle-orm/pglite").PgliteDatabase<Record<string, never>> & {
+        $client: PGlite;
+    };
+    client: PGlite;
+}>;

package/dist/db.js

@@ -0,0 +1,16 @@
+/**
+ * @deprecated — 레거시 싱글톤 DB 인스턴스.
+ * 새 코드에서는 ctx.db를 사용하세요.
+ * 서버의 createDatabase() (database.ts)가 실제 DB 연결을 관리합니다.
+ */
+import { PGlite } from "@electric-sql/pglite";
+import { drizzle } from "drizzle-orm/pglite";
+let pgliteInstance = null;
+/** @deprecated Use ctx.db instead */
+export async function createDb(dataDir = "./data") {
+    if (!pgliteInstance) {
+        pgliteInstance = new PGlite(dataDir);
+    }
+    const db = drizzle(pgliteInstance);
+    return { db, client: pgliteInstance };
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Platform Core — Convex-like Backend Framework
+ *
+ * Provides: query, mutation, storage, scheduler, auth
+ * All with Convex-compatible DX patterns.
+ */
+export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx } from "./reactive";
+export { query, mutation, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations } from "./reactive";
+export type { Storage } from "./storage";
+export { createScheduler, getSchedulerInfo } from "./scheduler";
+export type { Scheduler } from "./scheduler";
+export { v, parseArgs, GencowValidationError } from "./v";
+export type { Validator, Infer, InferArgs } from "./v";
+export { withRetry } from "./retry";
+export type { RetryOptions } from "./retry";
+export { cronJobs } from "./crons";
+export type { CronJobsBuilder, CronJobDef, IntervalOptions, DailyOptions, WeeklyOptions } from "./crons";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Platform Core — Convex-like Backend Framework
+ *
+ * Provides: query, mutation, storage, scheduler, auth
+ * All with Convex-compatible DX patterns.
+ */
+export { query, mutation, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations } from "./reactive";
+export { createScheduler, getSchedulerInfo } from "./scheduler";
+export { v, parseArgs, GencowValidationError } from "./v";
+export { withRetry } from "./retry";
+export { cronJobs } from "./crons";

package/dist/reactive.d.ts

@@ -0,0 +1,113 @@
+import type { WSContext } from "hono/ws";
+import type { Storage } from "./storage";
+import type { Scheduler } from "./scheduler";
+import { type InferArgs } from "./v";
+export interface UserIdentity {
+    id: string;
+    email: string;
+    name?: string;
+}
+export interface AuthCtx {
+    /** 현재 유저 반환 (비로그인 시 null) — Convex의 ctx.auth.getUserIdentity() */
+    getUserIdentity(): UserIdentity | null;
+    /** 현재 유저 반환 (비로그인 시 401 throw) */
+    requireAuth(): UserIdentity;
+}
+/**
+ * mutation handler 내에서 구독자들에게 데이터를 즉시 push합니다.
+ * 클라이언트는 이 데이터를 받아 re-fetch 없이 state를 업데이트합니다.
+ */
+export interface RealtimeCtx {
+    /**
+     * @param queryKey - 업데이트할 쿼리 키 (예: "tasks.list")
+     * @param data     - push할 데이터 (해당 query 결과와 동일한 타입)
+     *
+     * @example
+     *   const freshList = await ctx.db.select().from(tasks);
+     *   ctx.realtime.emit("tasks.list", freshList);
+     */
+    emit(queryKey: string, data: unknown): void;
+}
+/**
+ * 사용자 함수(query/mutation)에 주입되는 컨텍스트.
+ * Convex의 ctx 패턴과 동일하게, 이 객체를 통해서만 DB/Storage/Auth에 접근 가능.
+ * fs, child_process 등 원시 Node.js API는 노출되지 않음.
+ */
+export interface GencowCtx {
+    /** Drizzle DB 인스턴스 — ctx.db.select().from(table) */
+    db: any;
+    /** 인증 컨텍스트 — ctx.auth.getUserIdentity() */
+    auth: AuthCtx;
+    /** 파일 스토리지 — ctx.storage.store(), ctx.storage.getUrl() */
+    storage: Storage;
+    /** 스케줄러 — ctx.scheduler.runAfter(), ctx.scheduler.cron() */
+    scheduler: Scheduler;
+    /** 실시간 push — ctx.realtime.emit(queryKey, data) */
+    realtime: RealtimeCtx;
+    /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
+    retry: <T>(fn: () => Promise<T>, options?: import("./retry").RetryOptions) => Promise<T>;
+}
+type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+type MutationHandler<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;
+    _args?: InferArgs<TSchema>;
+    _return?: TReturn;
+}
+export interface MutationDef<TSchema = any, TReturn = any> {
+    invalidates: string[];
+    handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+    argsSchema?: TSchema;
+    _args?: InferArgs<TSchema>;
+    _return?: TReturn;
+}
+export declare function query<TSchema = any, TReturn = any>(key: string, handlerOrDef: QueryHandler<InferArgs<TSchema>, TReturn> | {
+    args?: TSchema;
+    handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+}): QueryDef<TSchema, TReturn>;
+export declare function mutation<TSchema = any, TReturn = any>(invalidatesOrDef: string[] | {
+    name?: string;
+    args?: TSchema;
+    invalidates: string[];
+    handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+}, handler?: MutationHandler<InferArgs<TSchema>, TReturn>, name?: string): MutationDef<TSchema, TReturn>;
+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;
+/**
+ * After a mutation, re-run invalidated queries and push results
+ * to all subscribers — Convex의 자동 reactive 업데이트 재현
+ */
+/**
+ * mutation 실행 시점에 생성되는 RealtimeCtx.
+ * emit() 호출 시 해당 queryKey를 구독 중인 WebSocket 클라이언트들에게
+ * data를 즉시 push합니다.
+ *
+ * 💡 Batching: 같은 queryKey에 대한 emit이 50ms 내에 여러 번 호출되면
+ * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
+ *
+ * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ */
+export declare function buildRealtimeCtx(): RealtimeCtx;
+/**
+ * mutation이 끝난 후 호출되는 legacy fallback.
+ * `ctx.realtime.emit()`을 사용하는 새 mutation에서는 빈 배열([])을 전달하면 됩니다.
+ *
+ * invalidate 신호만 broadcast하여 클라이언트가 re-fetch 여부를 결정하게 합니다.
+ * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
+ *
+ * @deprecated ctx.realtime.emit() 사용 권장
+ */
+export declare function invalidateQueries(queryKeys: string[], ctx: GencowCtx): 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;
+export declare function getRegisteredQueries(): string[];
+export declare function getRegisteredMutations(): (MutationDef & {
+    name: string;
+})[];
+export {};

package/dist/reactive.js

@@ -0,0 +1,175 @@
+// ─── Registry ───────────────────────────────────────────
+const queryRegistry = new Map();
+const mutationRegistry = [];
+const subscribers = new Map();
+/**
+ * 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).
+ */
+const connectedClients = new Set();
+// ─── Public API (Convex-style) ──────────────────────────
+export function query(key, handlerOrDef) {
+    let handler;
+    let argsSchema;
+    if (typeof handlerOrDef === "function") {
+        handler = handlerOrDef;
+    }
+    else {
+        handler = handlerOrDef.handler;
+        argsSchema = handlerOrDef.args;
+    }
+    const def = { key, handler, argsSchema };
+    queryRegistry.set(key, def);
+    return def;
+}
+let mutationCounter = 0;
+export function mutation(invalidatesOrDef, handler, name) {
+    let invalidates;
+    let argsSchema;
+    let actualHandler;
+    let mutName;
+    if (Array.isArray(invalidatesOrDef)) {
+        // Legacy style: mutation([...], handler, "name")
+        invalidates = invalidatesOrDef;
+        actualHandler = handler;
+        mutName = name || `mutation_${++mutationCounter}`;
+    }
+    else {
+        // New object style: mutation({ name?, invalidates, args?, handler })
+        invalidates = invalidatesOrDef.invalidates;
+        actualHandler = invalidatesOrDef.handler;
+        argsSchema = invalidatesOrDef.args;
+        mutName = invalidatesOrDef.name || name || `mutation_${++mutationCounter}`;
+    }
+    const def = {
+        name: mutName,
+        invalidates,
+        handler: actualHandler,
+        argsSchema
+    };
+    mutationRegistry.push(def);
+    return def;
+}
+// ─── WebSocket subscription management ──────────────────
+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);
+    }
+}
+/**
+ * After a mutation, re-run invalidated queries and push results
+ * to all subscribers — Convex의 자동 reactive 업데이트 재현
+ */
+/**
+ * mutation 실행 시점에 생성되는 RealtimeCtx.
+ * emit() 호출 시 해당 queryKey를 구독 중인 WebSocket 클라이언트들에게
+ * data를 즉시 push합니다.
+ *
+ * 💡 Batching: 같은 queryKey에 대한 emit이 50ms 내에 여러 번 호출되면
+ * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
+ *
+ * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ */
+export function buildRealtimeCtx() {
+    const pendingEmits = new Map();
+    return {
+        emit(queryKey, data) {
+            // 기존 pending timer가 있으면 취소 (debounce)
+            const existing = pendingEmits.get(queryKey);
+            if (existing)
+                clearTimeout(existing.timer);
+            const timer = setTimeout(() => {
+                pendingEmits.delete(queryKey);
+                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 });
+        }
+    };
+}
+/**
+ * mutation이 끝난 후 호출되는 legacy fallback.
+ * `ctx.realtime.emit()`을 사용하는 새 mutation에서는 빈 배열([])을 전달하면 됩니다.
+ *
+ * invalidate 신호만 broadcast하여 클라이언트가 re-fetch 여부를 결정하게 합니다.
+ * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
+ *
+ * @deprecated ctx.realtime.emit() 사용 권장
+ */
+export async function invalidateQueries(queryKeys, ctx) {
+    if (queryKeys.length === 0)
+        return; // emit() 방식에서는 no-op
+    // invalidate 신호만 broadcast (re-fetch는 클라이언트 결정에 맡김)
+    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 {
+        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
+    }
+}
+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());
+}
+export function getRegisteredMutations() {
+    return [...mutationRegistry];
+}