@gencow/core 0.1.12 → 0.1.14

package/dist/crud.d.ts

@@ -1,42 +1,84 @@
-import type { PgDatabase, PgTable } from "drizzle-orm/pg-core";
+/**
+ * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v2)
+ *
+ * 사용자 코드 5줄로 완전한 CRUD API를 자동 생성:
+ *
+ * @example
+ * ```ts
+ * import { crud } from "@gencow/core";
+ * import { tasks } from "./schema";
+ *
+ * // query(tasks.list), query(tasks.get), mutation(tasks.create/update/remove) 자동 등록
+ * export const { list, get, create, update, remove } = crud(tasks);
+ * ```
+ *
+ * list 반환값: `{ data: T[], total: number }`
+ *   → 프론트: `const result = useQuery(api.tasks.list); result?.data.map(...)`
+ *   → total은 동일 필터 조건의 전체 레코드 수 (페이지네이션 UI 지원)
+ *
+ * 내부적으로 query()/mutation()을 호출하여 글로벌 레지스트리에 등록하므로,
+ * 프론트엔드에서 useQuery(api.tasks.list) / useMutation(api.tasks.create) 로 바로 사용 가능.
+ *
+ * 📄 Spec: docs/specs/spec-crud-v2-enhancements.md
+ * 📦 참조: saas-js/drizzle-crud 팩토리 패턴
+ */
+import type { PgTable } from "drizzle-orm/pg-core";
 type CrudOptions<T extends PgTable> = {
+    /** 검색 대상 필드 — list의 search 파라미터에 사용 */
     searchFields?: (keyof T["_"]["columns"])[];
+    /** 소프트 삭제 컬럼 (e.g. deletedAt) */
     softDelete?: {
         field: keyof T["_"]["columns"];
     };
+    /** 필터링 허용 필드 — allowedFilters에 없는 키는 무시 (보안) */
     allowedFilters?: (keyof T["_"]["columns"])[];
+    /** 기본 페이지 크기 (default: 20) */
     defaultLimit?: number;
+    /** 최대 페이지 크기 (default: 100) */
     maxLimit?: number;
+    /** 라이프사이클 훅 */
     hooks?: {
         beforeCreate?: (data: any) => any | Promise<any>;
         beforeUpdate?: (data: any) => any | Promise<any>;
     };
+    /** true면 인증 없이 접근 가능 (기본: false — Secure by Default) */
+    public?: boolean;
+    /** true면 mutation 후 realtime push (기본: true) */
+    realtime?: boolean;
+    /** 키 접두사 오버라이드 (기본: 테이블명) */
+    prefix?: string;
 };
-export declare function gencowCrud(db: PgDatabase<any, any, any>): <T extends PgTable>(table: T, options?: CrudOptions<T>) => {
-    create: (data: any) => Promise<any>;
-    findById: (id: any) => Promise<any | null>;
-    list: (params?: {
-        page?: number;
-        limit?: number;
-        search?: string;
-        filters?: Record<string, any>;
-        orderBy?: {
-            field: string;
-            direction: "asc" | "desc";
-        }[];
-        includeDeleted?: boolean;
-    }) => Promise<{
-        results: {
-            [x: string]: any;
-        }[];
-        page: number;
-        limit: number;
+/**
+ * 테이블을 받아 query/mutation을 자동 등록하고,
+ * { list, get, create, update, remove } 를 반환한다.
+ *
+ * list 반환값: `{ data: T[], total: number }`
+ *
+ * @example
+ * ```ts
+ * export const { list, get, create, update, remove } = crud(tasks);
+ * export const { list, get, create, update, remove } = crud(tasks, { public: true });
+ * ```
+ */
+export declare function crud<T extends PgTable>(table: T, options?: CrudOptions<T>): {
+    list: import("./reactive").QueryDef<{
+        page: import("./v").Validator<number | undefined>;
+        limit: import("./v").Validator<number | undefined>;
+        search: import("./v").Validator<string | undefined>;
+        orderBy: import("./v").Validator<string | undefined>;
+        orderDir: import("./v").Validator<string | undefined>;
+        filters: import("./v").Validator<any>;
+    }, {
+        data: any;
         total: number;
     }>;
-    update: (id: any, data: any) => Promise<any>;
-    deleteOne: (id: any) => Promise<void>;
-    restore: (id: any) => Promise<void>;
-    bulkCreate: (dataArray: any[]) => Promise<any[]>;
-    bulkDelete: (ids: any[]) => Promise<void>;
+    get: import("./reactive").QueryDef<{
+        id: import("./v").Validator<string> | import("./v").Validator<number>;
+    }, any>;
+    create: import("./reactive").MutationDef<any, any>;
+    update: import("./reactive").MutationDef<any, any>;
+    remove: import("./reactive").MutationDef<any, {
+        success: boolean;
+    }>;
 };
 export {};

package/dist/crud.js

@@ -1,130 +1,251 @@
-import { eq, or, and, ilike, desc, asc, inArray, count, sql } from "drizzle-orm";
-export function gencowCrud(db) {
-    return function createCrud(table, options) {
-        const anyTable = table;
-        const pk = anyTable["id"];
-        if (!pk) {
-            throw new Error(`[gencowCrud] Table ${anyTable["_"]["name"]} must have an 'id' column.`);
+/**
+ * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v2)
+ *
+ * 사용자 코드 5줄로 완전한 CRUD API를 자동 생성:
+ *
+ * @example
+ * ```ts
+ * import { crud } from "@gencow/core";
+ * import { tasks } from "./schema";
+ *
+ * // query(tasks.list), query(tasks.get), mutation(tasks.create/update/remove) 자동 등록
+ * export const { list, get, create, update, remove } = crud(tasks);
+ * ```
+ *
+ * list 반환값: `{ data: T[], total: number }`
+ *   → 프론트: `const result = useQuery(api.tasks.list); result?.data.map(...)`
+ *   → total은 동일 필터 조건의 전체 레코드 수 (페이지네이션 UI 지원)
+ *
+ * 내부적으로 query()/mutation()을 호출하여 글로벌 레지스트리에 등록하므로,
+ * 프론트엔드에서 useQuery(api.tasks.list) / useMutation(api.tasks.create) 로 바로 사용 가능.
+ *
+ * 📄 Spec: docs/specs/spec-crud-v2-enhancements.md
+ * 📦 참조: saas-js/drizzle-crud 팩토리 패턴
+ */
+import { eq, desc, asc, ilike, or, and, count as drizzleCount, getTableName } from "drizzle-orm";
+import { query, mutation } from "./reactive";
+import { v } from "./v";
+// ─── Helpers ────────────────────────────────────────────
+/**
+ * id 컬럼의 Drizzle dataType을 검사하여 적절한 validator를 반환.
+ * serial/integer/bigint → v.number()
+ * text/uuid/varchar → v.string()
+ */
+function detectIdType(column) {
+    const colType = column.dataType;
+    if (colType === "string")
+        return v.string();
+    return v.number();
+}
+// ─── crud — Zero-Boilerplate API Factory ──────────
+/**
+ * 테이블을 받아 query/mutation을 자동 등록하고,
+ * { list, get, create, update, remove } 를 반환한다.
+ *
+ * list 반환값: `{ data: T[], total: number }`
+ *
+ * @example
+ * ```ts
+ * export const { list, get, create, update, remove } = crud(tasks);
+ * export const { list, get, create, update, remove } = crud(tasks, { public: true });
+ * ```
+ */
+export function crud(table, options) {
+    const anyTable = table;
+    const tableName = getTableName(table); // Drizzle 공식 API
+    const prefix = options?.prefix || tableName;
+    const isPublic = options?.public ?? false;
+    const useRealtime = options?.realtime ?? true;
+    const defaultLimit = options?.defaultLimit ?? 20;
+    const maxLimit = options?.maxLimit ?? 100;
+    const pk = anyTable["id"];
+    if (!pk) {
+        throw new Error(`[crud] Table "${tableName}" must have an 'id' column.`);
+    }
+    // id 타입 자동 감지 (serial → v.number(), text/uuid → v.string())
+    const idValidator = detectIdType(pk);
+    // createdAt 컬럼 (정렬용, 없으면 id 사용)
+    const createdAtCol = anyTable["createdAt"];
+    const defaultOrderCol = createdAtCol || pk;
+    // userId 컬럼 (자동 주입용)
+    const userIdCol = anyTable["userId"];
+    // ── 내부 헬퍼: WHERE 조건 빌드 (list + count + realtime 공유) ──
+    function buildWhereConditions(args) {
+        const conditions = [];
+        // Soft delete
+        if (options?.softDelete) {
+            const sdField = anyTable[options.softDelete.field];
+            conditions.push(eq(sdField, null));
         }
-        async function create(data) {
-            let insertData = { ...data };
-            if (options?.hooks?.beforeCreate) {
-                insertData = await options.hooks.beforeCreate(insertData);
-            }
-            const [result] = await db.insert(anyTable).values(insertData).returning();
-            return result;
+        // Search
+        if (args?.search && options?.searchFields?.length) {
+            const searchConds = options.searchFields.map((f) => ilike(anyTable[f], `%${args.search}%`));
+            conditions.push(or(...searchConds));
         }
-        async function findById(id) {
-            let whereCond = eq(pk, id);
-            if (options?.softDelete) {
-                const sdField = anyTable[options.softDelete.field];
-                whereCond = and(whereCond, sql `${sdField} IS NULL`);
+        // Dynamic filters (allowedFilters 화이트리스트만 허용)
+        if (args?.filters && options?.allowedFilters?.length) {
+            for (const [key, value] of Object.entries(args.filters)) {
+                if (options.allowedFilters.includes(key) && anyTable[key]) {
+                    conditions.push(eq(anyTable[key], value));
+                }
+                // allowedFilters에 없는 키는 무시 (보안)
             }
-            const [result] = await db.select().from(anyTable).where(whereCond).limit(1);
-            return result || null;
         }
-        async function list(params) {
-            const page = Math.max(1, params?.page || 1);
-            const limit = Math.min(Math.max(1, params?.limit || options?.defaultLimit || 20), options?.maxLimit || 100);
+        return conditions.length > 0 ? and(...conditions) : undefined;
+    }
+    // ── 내부 헬퍼: list+count 데이터 가져오기 (realtime push용 재사용) ──
+    // 순차 실행: 소규모 커넥션 풀 환경에서 동시 점유 방지
+    // ⚠️ limit/offset 없이 전체 SELECT — 대량 데이터 시 성능 저하 주의
+    // TODO(P2): realtime emit 시 invalidation 메시지만 전송하고 클라이언트가 re-fetch하는 패턴 검토
+    async function fetchListWithTotal(db, whereClause) {
+        const data = await db.select().from(anyTable).where(whereClause).orderBy(desc(defaultOrderCol));
+        const countResult = await db.select({ count: drizzleCount() }).from(anyTable).where(whereClause);
+        return { data, total: Number(countResult[0]?.count ?? 0) };
+    }
+    // ── list ──────────────────────────────────────
+    const listDef = query(`${prefix}.list`, {
+        public: isPublic,
+        args: {
+            page: v.optional(v.number()),
+            limit: v.optional(v.number()),
+            search: v.optional(v.string()),
+            orderBy: v.optional(v.string()),
+            orderDir: v.optional(v.string()),
+            filters: v.optional(v.any()),
+        },
+        handler: async (ctx, args) => {
+            if (!isPublic)
+                ctx.auth.requireAuth();
+            const page = Math.max(1, args?.page || 1);
+            const limit = Math.min(Math.max(1, args?.limit || defaultLimit), maxLimit);
             const offset = (page - 1) * limit;
-            const conditions = [];
-            // Soft delete
-            if (options?.softDelete && !params?.includeDeleted) {
-                conditions.push(sql `${anyTable[options.softDelete.field]} IS NULL`);
+            const whereClause = buildWhereConditions(args);
+            // Order
+            let orderByClause;
+            if (args?.orderBy && anyTable[args.orderBy]) {
+                const col = anyTable[args.orderBy];
+                orderByClause = args.orderDir === "asc" ? asc(col) : desc(col);
             }
-            // Search
-            if (params?.search && options?.searchFields?.length) {
-                const searchConds = options.searchFields.map((f) => ilike(anyTable[f], `%${params.search}%`));
-                conditions.push(or(...searchConds));
-            }
-            // Filters
-            if (params?.filters && options?.allowedFilters) {
-                for (const [k, v] of Object.entries(params.filters)) {
-                    if (options.allowedFilters.includes(k)) {
-                        conditions.push(eq(anyTable[k], v));
-                    }
-                }
+            else {
+                orderByClause = desc(defaultOrderCol);
             }
-            const whereClause = conditions.length > 0 ? and(...conditions) : undefined;
-            // Order By
-            const orderByArgs = (params?.orderBy || []).map((o) => {
-                const col = anyTable[o.field];
-                return o.direction === 'desc' ? desc(col) : asc(col);
-            });
-            // Base count 
-            const [{ count: total }] = await db.select({ count: count() }).from(anyTable).where(whereClause);
-            const results = await db.select()
+            // SELECT + COUNT 순차 실행 — 소규모 커넥션 풀 환경에서 동시 점유 방지
+            // Note: data←→count 사이 INSERT/DELETE 시 total 불일치 가능 (BaaS 단일사용자/저부하에서 무시 가능)
+            // TODO(P2): 대규모 시 db.transaction() 래핑 검토
+            const results = await ctx.db.select()
                 .from(anyTable)
                 .where(whereClause)
-                .orderBy(...orderByArgs)
+                .orderBy(orderByClause)
                 .limit(limit)
                 .offset(offset);
+            const countResult = await ctx.db.select({ count: drizzleCount() })
+                .from(anyTable)
+                .where(whereClause);
             return {
-                results,
-                page,
-                limit,
-                total: Number(total),
+                data: results,
+                total: Number(countResult[0]?.count ?? 0),
             };
         }
-        async function update(id, data) {
-            let updateData = { ...data };
+    });
+    // ── get ───────────────────────────────────────
+    const getDef = query(`${prefix}.get`, {
+        public: isPublic,
+        args: { id: idValidator },
+        handler: async (ctx, args) => {
+            if (!isPublic)
+                ctx.auth.requireAuth();
+            let whereCond = eq(pk, args.id);
+            if (options?.softDelete) {
+                const sdField = anyTable[options.softDelete.field];
+                whereCond = and(whereCond, eq(sdField, null));
+            }
+            const [result] = await ctx.db.select().from(anyTable).where(whereCond).limit(1);
+            return result ?? null;
+        }
+    });
+    // ── create ────────────────────────────────────
+    const createDef = mutation(`${prefix}.create`, {
+        public: isPublic,
+        invalidates: [],
+        handler: async (ctx, args) => {
+            const user = isPublic ? null : ctx.auth.requireAuth();
+            let insertData = { ...args };
+            // userId 자동 주입 (테이블에 userId 컬럼이 있고 인증된 경우)
+            if (userIdCol && user && !insertData.userId) {
+                insertData.userId = user.id;
+            }
+            // beforeCreate 훅
+            if (options?.hooks?.beforeCreate) {
+                insertData = await options.hooks.beforeCreate(insertData);
+            }
+            const [result] = await ctx.db.insert(anyTable).values(insertData).returning();
+            // Realtime push — { data, total } 형태로 emit
+            if (useRealtime) {
+                const listResult = await fetchListWithTotal(ctx.db);
+                ctx.realtime.emit(`${prefix}.list`, listResult);
+            }
+            return result;
+        }
+    });
+    // ── update ────────────────────────────────────
+    const updateDef = mutation(`${prefix}.update`, {
+        public: isPublic,
+        invalidates: [],
+        handler: async (ctx, args) => {
+            if (!isPublic)
+                ctx.auth.requireAuth();
+            const { id, ...updates } = args;
+            let updateData = { ...updates };
+            // updatedAt 자동 갱신
+            if (anyTable["updatedAt"]) {
+                updateData.updatedAt = new Date();
+            }
+            // beforeUpdate 훅
             if (options?.hooks?.beforeUpdate) {
                 updateData = await options.hooks.beforeUpdate(updateData);
             }
-            const [result] = await db.update(anyTable)
+            const [result] = await ctx.db.update(anyTable)
                 .set(updateData)
                 .where(eq(pk, id))
                 .returning();
+            // Realtime push (list + get 양쪽) — { data, total } 형태
+            if (useRealtime) {
+                const listResult = await fetchListWithTotal(ctx.db);
+                ctx.realtime.emit(`${prefix}.list`, listResult);
+                ctx.realtime.emit(`${prefix}.get`, result);
+            }
             return result;
         }
-        async function deleteOne(id) {
+    });
+    // ── remove ────────────────────────────────────
+    const removeDef = mutation(`${prefix}.remove`, {
+        public: isPublic,
+        invalidates: [],
+        handler: async (ctx, args) => {
+            if (!isPublic)
+                ctx.auth.requireAuth();
             if (options?.softDelete) {
                 const sdField = options.softDelete.field;
-                await db.update(anyTable)
+                await ctx.db.update(anyTable)
                     .set({ [sdField]: new Date() })
-                    .where(eq(pk, id));
+                    .where(eq(pk, args.id));
             }
             else {
-                await db.delete(anyTable).where(eq(pk, id));
-            }
-        }
-        async function restore(id) {
-            if (options?.softDelete) {
-                const sdField = options.softDelete.field;
-                await db.update(anyTable)
-                    .set({ [sdField]: null })
-                    .where(eq(pk, id));
+                await ctx.db.delete(anyTable).where(eq(pk, args.id));
             }
-        }
-        async function bulkCreate(dataArray) {
-            let insertData = [...dataArray];
-            if (options?.hooks?.beforeCreate) {
-                insertData = await Promise.all(insertData.map((d) => options.hooks.beforeCreate(d)));
-            }
-            return await db.insert(anyTable).values(insertData).returning();
-        }
-        async function bulkDelete(ids) {
-            if (ids.length === 0)
-                return;
-            if (options?.softDelete) {
-                const sdField = options.softDelete.field;
-                await db.update(anyTable)
-                    .set({ [sdField]: new Date() })
-                    .where(inArray(pk, ids));
-            }
-            else {
-                await db.delete(anyTable).where(inArray(pk, ids));
+            // Realtime push — { data, total } 형태
+            if (useRealtime) {
+                const listResult = await fetchListWithTotal(ctx.db);
+                ctx.realtime.emit(`${prefix}.list`, listResult);
             }
+            return { success: true };
         }
-        return {
-            create,
-            findById,
-            list,
-            update,
-            deleteOne,
-            restore,
-            bulkCreate,
-            bulkDelete,
-        };
+    });
+    return {
+        list: listDef,
+        get: getDef,
+        create: createDef,
+        update: updateDef,
+        remove: removeDef,
     };
 }

package/dist/index.d.ts

@@ -19,4 +19,5 @@ export { defineAuth } from "./auth-config";
 export type { GencowAuthConfig, AuthEmailVerification } from "./auth-config";
 export { ownerRls } from "./rls";
 export { createRlsDb } from "./rls-db";
-export { gencowCrud } from "./crud";
+export { crud } from "./crud";
+export { crud as gencowCrud } from "./crud";

package/dist/index.js

@@ -13,4 +13,6 @@ export { defineAuth } from "./auth-config";
 // ─── RLS + CRUD Factory ───────────
 export { ownerRls } from "./rls";
 export { createRlsDb } from "./rls-db";
-export { gencowCrud } from "./crud";
+export { crud } from "./crud";
+// Deprecated alias — 하위호환용, 향후 메이저 버전에서 제거 예정
+export { crud as gencowCrud } from "./crud";

package/dist/scheduler.js

@@ -131,7 +131,15 @@ export function createScheduler() {
             actions.set(name, handler);
         },
         async executeAction(name, args) {
-            await executeAction(name, args);
+            try {
+                await executeAction(name, args);
+            }
+            catch (error) {
+                // 공개 API는 에러를 삼긴다 (호출자 크래시 방지)
+                // handler 에러도 로깅 (내부 함수는 미등록만 로깅, handler 에러는 미로깅)
+                const msg = error instanceof Error ? error.message : String(error);
+                console.error(`[scheduler] executeAction("${name}") failed: ${msg}`);
+            }
         },
     };
 }

package/package.json

@@ -1,41 +1,42 @@
 {
-  "name": "@gencow/core",
-  "version": "0.1.12",
-  "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+    "name": "@gencow/core",
+    "version": "0.1.14",
+    "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "require": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./server": {
+            "import": "./dist/server.js",
+            "require": "./dist/server.js",
+            "types": "./dist/server.d.ts"
+        }
     },
-    "./server": {
-      "import": "./dist/server.js",
-      "require": "./dist/server.js",
-      "types": "./dist/server.d.ts"
+    "files": [
+        "dist/",
+        "src/"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "npm run build",
+        "postinstall": "tsc"
+    },
+    "dependencies": {
+        "@electric-sql/pglite": "^0.3.15",
+        "drizzle-orm": "^0.45.1",
+        "hono": "^4.12.0",
+        "node-cron": "^4.2.1"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.9",
+        "@types/node": "^25.3.0",
+        "@types/node-cron": "^3.0.11",
+        "typescript": "^5.9.3"
     }
-  },
-  "files": [
-    "dist/",
-    "src/"
-  ],
-  "dependencies": {
-    "@electric-sql/pglite": "^0.3.15",
-    "drizzle-orm": "^0.45.1",
-    "hono": "^4.12.0",
-    "node-cron": "^4.2.1"
-  },
-  "devDependencies": {
-    "@types/bun": "^1.3.9",
-    "@types/node": "^25.3.0",
-    "@types/node-cron": "^3.0.11",
-    "typescript": "^5.9.3"
-  },
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "postinstall": "tsc"
-  }
-}
+}