@gencow/core 0.1.13 → 0.1.15

package/src/crud.ts

@@ -1,5 +1,5 @@
 /**
- * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v2)
+ * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v3)
  *
  * 사용자 코드 5줄로 완전한 CRUD API를 자동 생성:
  *
@@ -19,11 +19,11 @@
  * 내부적으로 query()/mutation()을 호출하여 글로벌 레지스트리에 등록하므로,
  * 프론트엔드에서 useQuery(api.tasks.list) / useMutation(api.tasks.create) 로 바로 사용 가능.
  *
- * 📄 Spec: docs/specs/spec-crud-v2-enhancements.md
+ * 📄 Spec: docs/specs/spec-crud-advanced-filters.md (v3), docs/specs/spec-crud-v2-enhancements.md (v2)
  * 📦 참조: saas-js/drizzle-crud 팩토리 패턴
  */
 
-import { eq, desc, asc, ilike, or, and, count as drizzleCount, getTableName, getTableColumns, type SQL } from "drizzle-orm";
+import { eq, ne, gt, gte, lt, lte, desc, asc, like, ilike, inArray, notInArray, 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";
@@ -67,6 +67,128 @@ function detectIdType(column: AnyPgColumn) {
     return v.number();
 }
 
+// ─── v3 Filter Engine — 재귀적 동적 필터링 ──────────────
+
+/** 재귀 필터 최대 깊이 — DoS 방어 (깊이 초과 시 조건 묵살) */
+const MAX_FILTER_DEPTH = 5;
+
+/** 지원 연산자 목록 */
+const FILTER_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'ilike'] as const;
+type FilterOp = typeof FILTER_OPS[number];
+
+function isValidFilterOp(op: string): op is FilterOp {
+    return (FILTER_OPS as readonly string[]).includes(op);
+}
+
+/**
+ * 단일 필터 연산자를 Drizzle SQL 조건으로 변환.
+ * 지원하지 않는 op이거나 값 타입이 맞지 않으면 undefined 반환 (묵살).
+ */
+export function applyFilterOp(col: AnyPgColumn, op: FilterOp, value: unknown): SQL | undefined {
+    switch (op) {
+        case 'eq':    return eq(col, value);
+        case 'ne':    return ne(col, value);
+        case 'gt':    return gt(col, value as any);
+        case 'gte':   return gte(col, value as any);
+        case 'lt':    return lt(col, value as any);
+        case 'lte':   return lte(col, value as any);
+        case 'in':
+            if (!Array.isArray(value) || value.length === 0) return undefined;
+            return inArray(col, value);
+        case 'nin':
+            if (!Array.isArray(value) || value.length === 0) return undefined;
+            return notInArray(col, value);
+        case 'like':
+            if (typeof value !== 'string') return undefined;
+            return like(col, value);
+        case 'ilike':
+            if (typeof value !== 'string') return undefined;
+            return ilike(col, value);
+        default:      return undefined;
+    }
+}
+
+/**
+ * 재귀적 필터 노드 파싱 — OR/AND 논리 중첩 + 연산자 매핑.
+ *
+ * @param node         - 필터 JSON 객체
+ * @param table        - Drizzle PgTable (컬럼 매핑)
+ * @param allowedFields - 허용 필드 화이트리스트 (미지정 시 모든 테이블 컬럼 허용)
+ *
+ * @example
+ * ```ts
+ * // 암묵적 eq (v2 하위호환)
+ * parseFilterNode({ status: 'active' }, table)
+ *   → and(eq(table.status, 'active'))
+ *
+ * // 명시적 연산자
+ * parseFilterNode({ qty: { op: 'gte', value: 10 } }, table)
+ *   → and(gte(table.qty, 10))
+ *
+ * // OR / AND 중첩
+ * parseFilterNode({ OR: [{ a: 1 }, { b: { op: 'gt', value: 5 } }] }, table)
+ *   → or(eq(table.a, 1), gt(table.b, 5))
+ * ```
+ */
+export function parseFilterNode(
+    node: Record<string, unknown>,
+    table: any,
+    allowedFields?: readonly string[],
+    depth: number = 0,
+): SQL | undefined {
+    // DoS 방어: 재귀 깊이 제한 초과 시 조건 묵살
+    if (depth > MAX_FILTER_DEPTH) return undefined;
+
+    const conditions: SQL[] = [];
+
+    for (const [key, val] of Object.entries(node)) {
+        // ── OR 논리 그룹 ──
+        if (key === 'OR') {
+            if (!Array.isArray(val)) continue; // 잘못된 타입 → 묵살
+            const orConds = val
+                .filter((child): child is Record<string, unknown> =>
+                    child != null && typeof child === 'object' && !Array.isArray(child))
+                .map((child) => parseFilterNode(child, table, allowedFields, depth + 1))
+                .filter((c): c is SQL => c !== undefined);
+            if (orConds.length > 0) conditions.push(or(...orConds)!);
+            continue;
+        }
+
+        // ── AND 논리 그룹 ──
+        if (key === 'AND') {
+            if (!Array.isArray(val)) continue;
+            const andConds = val
+                .filter((child): child is Record<string, unknown> =>
+                    child != null && typeof child === 'object' && !Array.isArray(child))
+                .map((child) => parseFilterNode(child, table, allowedFields, depth + 1))
+                .filter((c): c is SQL => c !== undefined);
+            if (andConds.length > 0) conditions.push(and(...andConds)!);
+            continue;
+        }
+
+        // ── 컬럼 필터 ──
+        // allowedFields 화이트리스트 검증 (재귀적으로 OR/AND 내부에도 적용됨)
+        if (allowedFields && !allowedFields.includes(key)) continue;
+
+        const col = table[key] as AnyPgColumn | undefined;
+        if (!col) continue;
+
+        // 명시적 연산자: { op: 'gte', value: 10 }
+        if (val != null && typeof val === 'object' && !Array.isArray(val) && 'op' in val) {
+            const { op, value } = val as { op: string; value: unknown };
+            if (!isValidFilterOp(op)) continue; // 미지원 op → 묵살
+            const cond = applyFilterOp(col, op, value);
+            if (cond) conditions.push(cond);
+            continue;
+        }
+
+        // 암묵적 eq (v2 하위호환): { status: 'active' } → eq(status, 'active')
+        conditions.push(eq(col, val));
+    }
+
+    return conditions.length > 0 ? and(...conditions) : undefined;
+}
+
 // ─── crud — Zero-Boilerplate API Factory ──────────
 
 /**
@@ -123,25 +245,29 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
             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에 없는 키는 무시 (보안)
-            }
+        // Dynamic filters — v3 재귀적 파싱 엔진 (OR/AND 중첩, 연산자 매핑)
+        // allowedFilters 설정 시: 화이트리스트 필드만 허용 (재귀 검증)
+        // allowedFilters 미설정 시: 필터 전체 무시 (Secure by Default — v2 호환)
+        if (args?.filters && typeof args.filters === 'object' && options?.allowedFilters?.length) {
+            const allowedFields = options.allowedFilters as unknown as string[];
+            const filterCondition = parseFilterNode(
+                args.filters as Record<string, unknown>,
+                anyTable,
+                allowedFields,
+            );
+            if (filterCondition) conditions.push(filterCondition);
         }
 
         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: 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),
-        ]);
+        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) };
     }
 
@@ -175,18 +301,18 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
                 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),
-            ]);
+            // SELECT + COUNT 순차 실행 — 소규모 커넥션 풀 환경에서 동시 점유 방지
+            // Note: data←→count 사이 INSERT/DELETE 시 total 불일치 가능 (BaaS 단일사용자/저부하에서 무시 가능)
+            // TODO(P2): 대규모 시 db.transaction() 래핑 검토
+            const results = await ctx.db.select()
+                .from(anyTable)
+                .where(whereClause)
+                .orderBy(orderByClause)
+                .limit(limit)
+                .offset(offset);
+            const countResult = await ctx.db.select({ count: drizzleCount() })
+                .from(anyTable)
+                .where(whereClause);
 
             return {
                 data: results,

package/src/index.ts

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