@gencow/core 0.1.11 → 0.1.13

package/src/crud.ts

@@ -1,174 +1,322 @@
-import { eq, or, and, ilike, desc, asc, inArray, count, sql, type SQL } from "drizzle-orm";
-import type { PgDatabase, PgTable, AnyPgColumn } 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 { eq, desc, asc, ilike, or, and, count as drizzleCount, getTableName, getTableColumns, type SQL } from "drizzle-orm";
+import type { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
+import { query, mutation } from "./reactive";
+import { v } from "./v";
+
+// ─── Types ──────────────────────────────────────────────
 
 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 function gencowCrud(db: PgDatabase<any, any, any>) {
-    return function createCrud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
-        const anyTable = table as any;
-        const pk = anyTable["id"] as AnyPgColumn;
-        
-        if (!pk) {
-            throw new Error(`[gencowCrud] Table ${anyTable["_"]["name"]} must have an 'id' column.`);
+// ─── Helpers ────────────────────────────────────────────
+
+/**
+ * id 컬럼의 Drizzle dataType을 검사하여 적절한 validator를 반환.
+ * serial/integer/bigint → v.number()
+ * text/uuid/varchar → v.string()
+ */
+function detectIdType(column: AnyPgColumn) {
+    const colType = (column as any).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<T extends PgTable>(table: T, options?: CrudOptions<T>) {
+    const anyTable = table as any;
+    const tableName: string = 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"] as AnyPgColumn;
+
+    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"] as AnyPgColumn | undefined;
+    const defaultOrderCol = createdAtCol || pk;
+
+    // userId 컬럼 (자동 주입용)
+    const userIdCol = anyTable["userId"] as AnyPgColumn | undefined;
+
+    // ── 내부 헬퍼: WHERE 조건 빌드 (list + count + realtime 공유) ──
+    function buildWhereConditions(args: any): SQL | undefined {
+        const conditions: SQL[] = [];
+
+        // Soft delete
+        if (options?.softDelete) {
+            const sdField = anyTable[options.softDelete.field as string] as AnyPgColumn;
+            conditions.push(eq(sdField, null as any));
         }
-        
-        async function create(data: any): Promise<any> {
-            let insertData = { ...data };
-            if (options?.hooks?.beforeCreate) {
-                insertData = await options.hooks.beforeCreate(insertData);
+
+        // Search
+        if (args?.search && options?.searchFields?.length) {
+            const searchConds = options.searchFields.map(
+                (f) => ilike(anyTable[f as string] as AnyPgColumn, `%${args.search}%`)
+            );
+            conditions.push(or(...searchConds)!);
+        }
+
+        // Dynamic filters (allowedFilters 화이트리스트만 허용)
+        if (args?.filters && options?.allowedFilters?.length) {
+            for (const [key, value] of Object.entries(args.filters as Record<string, unknown>)) {
+                if (options.allowedFilters.includes(key as any) && anyTable[key]) {
+                    conditions.push(eq(anyTable[key] as AnyPgColumn, value));
+                }
+                // allowedFilters에 없는 키는 무시 (보안)
             }
-            const [result] = await db.insert(anyTable).values(insertData).returning();
-            return result;
         }
 
-        async function findById(id: any): Promise<any | null> {
-            let whereCond: SQL | undefined = eq(pk, id);
-            
+        return conditions.length > 0 ? and(...conditions) : undefined;
+    }
+
+    // ── 내부 헬퍼: list+count 데이터 가져오기 (realtime push용 재사용) ──
+    async function fetchListWithTotal(db: any, whereClause?: SQL) {
+        const [data, countResult] = await Promise.all([
+            db.select().from(anyTable).where(whereClause).orderBy(desc(defaultOrderCol)),
+            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: any, args: any) => {
+            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 whereClause = buildWhereConditions(args);
+
+            // Order
+            let orderByClause;
+            if (args?.orderBy && anyTable[args.orderBy]) {
+                const col = anyTable[args.orderBy] as AnyPgColumn;
+                orderByClause = args.orderDir === "asc" ? asc(col) : desc(col);
+            } else {
+                orderByClause = desc(defaultOrderCol);
+            }
+
+            // SELECT + COUNT 병렬 실행
+            const [results, countResult] = await Promise.all([
+                ctx.db.select()
+                    .from(anyTable)
+                    .where(whereClause)
+                    .orderBy(orderByClause)
+                    .limit(limit)
+                    .offset(offset),
+                ctx.db.select({ count: drizzleCount() })
+                    .from(anyTable)
+                    .where(whereClause),
+            ]);
+
+            return {
+                data: results,
+                total: Number(countResult[0]?.count ?? 0),
+            };
+        }
+    });
+
+    // ── get ───────────────────────────────────────
+
+    const getDef = query(`${prefix}.get`, {
+        public: isPublic,
+        args: { id: idValidator },
+        handler: async (ctx: any, args: any) => {
+            if (!isPublic) ctx.auth.requireAuth();
+
+            let whereCond: SQL = eq(pk, args.id);
+
             if (options?.softDelete) {
                 const sdField = anyTable[options.softDelete.field as string] as AnyPgColumn;
-                whereCond = and(whereCond, sql`${sdField} IS NULL`);
+                whereCond = and(whereCond, eq(sdField, null as any))!;
             }
-            
-            const [result] = await db.select().from(anyTable).where(whereCond).limit(1);
-            return result || null;
+
+            const [result] = await ctx.db.select().from(anyTable).where(whereCond).limit(1);
+            return result ?? null;
         }
+    });
 
-        async function list(params?: {
-            page?: number;
-            limit?: number;
-            search?: string;
-            filters?: Record<string, any>;
-            orderBy?: { field: string; direction: 'asc' | 'desc' }[];
-            includeDeleted?: boolean;
-        }) {
-            const page = Math.max(1, params?.page || 1);
-            const limit = Math.min(
-                Math.max(1, params?.limit || options?.defaultLimit || 20),
-                options?.maxLimit || 100
-            );
-            const offset = (page - 1) * limit;
+    // ── create ────────────────────────────────────
 
-            const conditions: SQL[] = [];
+    const createDef = mutation(`${prefix}.create`, {
+        public: isPublic,
+        invalidates: [],
+        handler: async (ctx: any, args: any) => {
+            const user = isPublic ? null : ctx.auth.requireAuth();
 
-            // Soft delete
-            if (options?.softDelete && !params?.includeDeleted) {
-               conditions.push(sql`${anyTable[options.softDelete.field as string]} IS NULL`);
-            }
+            let insertData = { ...args };
 
-            // Search
-            if (params?.search && options?.searchFields?.length) {
-                const searchConds = options.searchFields.map(
-                    (f) => ilike(anyTable[f as string] as AnyPgColumn, `%${params!.search}%`)
-                );
-                conditions.push(or(...searchConds)!);
+            // userId 자동 주입 (테이블에 userId 컬럼이 있고 인증된 경우)
+            if (userIdCol && user && !insertData.userId) {
+                insertData.userId = user.id;
             }
 
-            // Filters
-            if (params?.filters && options?.allowedFilters) {
-                for (const [k, v] of Object.entries(params.filters)) {
-                    if (options.allowedFilters.includes(k as keyof T["_"]["columns"])) {
-                        conditions.push(eq(anyTable[k] as AnyPgColumn, v));
-                    }
-                }
+            // beforeCreate 훅
+            if (options?.hooks?.beforeCreate) {
+                insertData = await options.hooks.beforeCreate(insertData);
             }
 
-            const whereClause = conditions.length > 0 ? and(...conditions) : undefined;
-
-            // Order By
-            const orderByArgs = (params?.orderBy || []).map((o) => {
-                const col = anyTable[o.field] as AnyPgColumn;
-                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()
-                .from(anyTable)
-                .where(whereClause)
-                .orderBy(...orderByArgs)
-                .limit(limit)
-                .offset(offset);
+            const [result] = await ctx.db.insert(anyTable).values(insertData).returning();
 
-            return {
-                results,
-                page,
-                limit,
-                total: Number(total),
-            };
+            // 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: any, args: any) => {
+            if (!isPublic) ctx.auth.requireAuth();
+
+            const { id, ...updates } = args;
 
-        async function update(id: any, data: any): Promise<any> {
-            let updateData = { ...data };
+            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();
-            return result;
-        }
 
-        async function deleteOne(id: any): Promise<void> {
-            if (options?.softDelete) {
-                const sdField = options.softDelete.field as string;
-                await db.update(anyTable)
-                    .set({ [sdField]: new Date() } as any)
-                    .where(eq(pk, id));
-            } else {
-                await db.delete(anyTable).where(eq(pk, id));
+            // 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);
             }
-        }
 
-        async function restore(id: any): Promise<void> {
-            if (options?.softDelete) {
-                const sdField = options.softDelete.field as string;
-                await db.update(anyTable)
-                    .set({ [sdField]: null } as any)
-                    .where(eq(pk, id));
-            }
+            return result;
         }
+    });
 
-        async function bulkCreate(dataArray: any[]): Promise<any[]> {
-            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();
-        }
+    // ── remove ────────────────────────────────────
+
+    const removeDef = mutation(`${prefix}.remove`, {
+        public: isPublic,
+        invalidates: [],
+        handler: async (ctx: any, args: any) => {
+            if (!isPublic) ctx.auth.requireAuth();
 
-        async function bulkDelete(ids: any[]): Promise<void> {
-            if (ids.length === 0) return;
             if (options?.softDelete) {
                 const sdField = options.softDelete.field as string;
-                await db.update(anyTable)
+                await ctx.db.update(anyTable)
                     .set({ [sdField]: new Date() } as any)
-                    .where(inArray(pk, ids));
+                    .where(eq(pk, args.id));
             } else {
-                await db.delete(anyTable).where(inArray(pk, ids));
+                await ctx.db.delete(anyTable).where(eq(pk, args.id));
+            }
+
+            // 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/src/index.ts

@@ -22,7 +22,10 @@ export type { GencowAuthConfig, AuthEmailVerification } 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/src/rls-db.ts

@@ -10,15 +10,20 @@ import type { PgDatabase } from "drizzle-orm/pg-core";
  *   → PgBouncer transaction 모드에서 안전
  */
 export function createRlsDb(db: PgDatabase<any, any, any>, userId: string) {
-    return {
-        ...db,
-        transaction: (async (callback: any, ...rest: any[]) => {
-            return await db.transaction(async (tx) => {
-                await tx.execute(
-                    sql`SELECT set_config('app.current_user_id', ${userId}, true)`
-                );
-                return await callback(tx);
-            }, ...rest as any);
-        }) as typeof db.transaction,
-    };
+    return new Proxy(db, {
+        get(target, prop, receiver) {
+            if (prop === "transaction") {
+                return async (callback: any, ...rest: any[]) => {
+                    return await target.transaction(async (tx) => {
+                        await tx.execute(
+                            sql`SELECT set_config('app.current_user_id', ${userId}, true)`
+                        );
+                        return await callback(tx);
+                    }, ...rest as any);
+                };
+            }
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === "function" ? value.bind(target) : value;
+        }
+    });
 }

package/src/scheduler.ts

@@ -214,7 +214,14 @@ export function createScheduler(): Scheduler {
         },
 
         async executeAction(name: string, args?: any): Promise<void> {
-            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/dist/scoped-db.d.ts

@@ -1,34 +0,0 @@
-/**
- * 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;