@gencow/core 0.1.13 → 0.1.15

package/dist/crud.d.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,10 +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 type { PgTable } from "drizzle-orm/pg-core";
+import { type SQL } from "drizzle-orm";
+import type { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 type CrudOptions<T extends PgTable> = {
     /** 검색 대상 필드 — list의 search 파라미터에 사용 */
     searchFields?: (keyof T["_"]["columns"])[];
@@ -48,6 +49,37 @@ type CrudOptions<T extends PgTable> = {
     /** 키 접두사 오버라이드 (기본: 테이블명) */
     prefix?: string;
 };
+/** 지원 연산자 목록 */
+declare const FILTER_OPS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin", "like", "ilike"];
+type FilterOp = typeof FILTER_OPS[number];
+/**
+ * 단일 필터 연산자를 Drizzle SQL 조건으로 변환.
+ * 지원하지 않는 op이거나 값 타입이 맞지 않으면 undefined 반환 (묵살).
+ */
+export declare function applyFilterOp(col: AnyPgColumn, op: FilterOp, value: unknown): SQL | 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 declare function parseFilterNode(node: Record<string, unknown>, table: any, allowedFields?: readonly string[], depth?: number): SQL | undefined;
 /**
  * 테이블을 받아 query/mutation을 자동 등록하고,
  * { list, get, create, update, remove } 를 반환한다.

package/dist/crud.js

@@ -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,10 +19,10 @@
  * 내부적으로 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 } from "drizzle-orm";
+import { eq, ne, gt, gte, lt, lte, desc, asc, like, ilike, inArray, notInArray, or, and, count as drizzleCount, getTableName } from "drizzle-orm";
 import { query, mutation } from "./reactive";
 import { v } from "./v";
 // ─── Helpers ────────────────────────────────────────────
@@ -37,6 +37,119 @@ function detectIdType(column) {
         return v.string();
     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'];
+function isValidFilterOp(op) {
+    return FILTER_OPS.includes(op);
+}
+/**
+ * 단일 필터 연산자를 Drizzle SQL 조건으로 변환.
+ * 지원하지 않는 op이거나 값 타입이 맞지 않으면 undefined 반환 (묵살).
+ */
+export function applyFilterOp(col, op, value) {
+    switch (op) {
+        case 'eq': return eq(col, value);
+        case 'ne': return ne(col, value);
+        case 'gt': return gt(col, value);
+        case 'gte': return gte(col, value);
+        case 'lt': return lt(col, value);
+        case 'lte': return lte(col, value);
+        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, table, allowedFields, depth = 0) {
+    // DoS 방어: 재귀 깊이 제한 초과 시 조건 묵살
+    if (depth > MAX_FILTER_DEPTH)
+        return undefined;
+    const conditions = [];
+    for (const [key, val] of Object.entries(node)) {
+        // ── OR 논리 그룹 ──
+        if (key === 'OR') {
+            if (!Array.isArray(val))
+                continue; // 잘못된 타입 → 묵살
+            const orConds = val
+                .filter((child) => child != null && typeof child === 'object' && !Array.isArray(child))
+                .map((child) => parseFilterNode(child, table, allowedFields, depth + 1))
+                .filter((c) => 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 != null && typeof child === 'object' && !Array.isArray(child))
+                .map((child) => parseFilterNode(child, table, allowedFields, depth + 1))
+                .filter((c) => c !== undefined);
+            if (andConds.length > 0)
+                conditions.push(and(...andConds));
+            continue;
+        }
+        // ── 컬럼 필터 ──
+        // allowedFields 화이트리스트 검증 (재귀적으로 OR/AND 내부에도 적용됨)
+        if (allowedFields && !allowedFields.includes(key))
+            continue;
+        const col = table[key];
+        if (!col)
+            continue;
+        // 명시적 연산자: { op: 'gte', value: 10 }
+        if (val != null && typeof val === 'object' && !Array.isArray(val) && 'op' in val) {
+            const { op, value } = val;
+            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 ──────────
 /**
  * 테이블을 받아 query/mutation을 자동 등록하고,
@@ -82,23 +195,24 @@ export function crud(table, options) {
             const searchConds = options.searchFields.map((f) => ilike(anyTable[f], `%${args.search}%`));
             conditions.push(or(...searchConds));
         }
-        // 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에 없는 키는 무시 (보안)
-            }
+        // 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;
+            const filterCondition = parseFilterNode(args.filters, 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, whereClause) {
-        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) };
     }
     // ── list ──────────────────────────────────────
@@ -128,18 +242,18 @@ export function crud(table, options) {
             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),
-            ]);
+            // 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,
                 total: Number(countResult[0]?.count ?? 0),

package/dist/index.d.ts

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

package/dist/index.js

@@ -13,6 +13,6 @@ export { defineAuth } 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";

package/package.json

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

package/src/__tests__/crud-codegen-integration.test.ts

@@ -0,0 +1,253 @@
+/**
+ * packages/core/src/__tests__/crud-codegen-integration.test.ts
+ *
+ * crud() → 레지스트리 등록 → codegen 인식 통합 테스트.
+ *
+ * 이 테스트의 존재 이유:
+ *   2026-04-02 사고: crud()가 query/mutation을 레지스트리에 자동 등록하지만,
+ *   codegen(gencow-extract.ts)이 getRegisteredQueries()/getRegisteredMutations()를
+ *   통해 이를 인식하는 전체 파이프라인이 검증되지 않았음.
+ *   결과: 사용자 모듈이 crud()를 사용하면 api.ts에 CRUD 엔드포인트가 누락됨.
+ *
+ * 검증 항목:
+ *   1. crud() 호출 후 getRegisteredQueries()에 {prefix}.list, {prefix}.get 포함
+ *   2. crud() 호출 후 getRegisteredMutations()에 {prefix}.create/update/remove 포함
+ *   3. 수동 query()/mutation()과 crud() 혼용 시 양쪽 모두 레지스트리에 존재
+ *   4. public/private 상태가 레지스트리에 정확히 반영
+ *   5. 여러 테이블의 crud()를 동시 호출해도 충돌 없음
+ *
+ * Run: bun test packages/core/src/__tests__/crud-codegen-integration.test.ts
+ *
+ * @see docs/analysis/analysis-test032-gencow-crud-api-mismatch.md
+ */
+
+import { describe, it, expect, beforeAll } from "bun:test";
+import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";
+
+import { crud } from "../crud";
+import {
+    query,
+    mutation,
+    getRegisteredQueries,
+    getRegisteredMutations,
+    getQueryDef,
+} from "../reactive";
+
+// ─── 테스트용 테이블 정의 ─────────────────────────────────────────────
+
+const keywords = pgTable("cg_keywords", {
+    id: serial("id").primaryKey(),
+    keyword: text("keyword").notNull(),
+    userId: text("user_id"),
+    createdAt: timestamp("created_at").defaultNow(),
+});
+
+const crawlLogs = pgTable("cg_crawl_logs", {
+    id: serial("id").primaryKey(),
+    status: text("status"),
+    createdAt: timestamp("created_at").defaultNow(),
+});
+
+const digests = pgTable("cg_digests", {
+    id: serial("id").primaryKey(),
+    title: text("title"),
+    content: text("content"),
+    createdAt: timestamp("created_at").defaultNow(),
+});
+
+const appSettings = pgTable("cg_app_settings", {
+    id: serial("id").primaryKey(),
+    key: text("key"),
+    value: text("value"),
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 1. crud() → 레지스트리 등록 → codegen 인식 전체 파이프라인
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("crud() → codegen 통합 — 다중 테이블", () => {
+    beforeAll(() => {
+        // test032 패턴 재현: 4개 모듈이 각각 crud() 호출
+        crud(keywords, { public: true });
+        crud(crawlLogs, { public: true });
+        crud(digests, { public: true });
+        crud(appSettings, { public: true });
+    });
+
+    it("4개 테이블의 list/get query가 모두 레지스트리에 등록된다", () => {
+        const queries = getRegisteredQueries();
+
+        // 각 테이블의 list + get = 8개
+        expect(queries).toContain("cg_keywords.list");
+        expect(queries).toContain("cg_keywords.get");
+        expect(queries).toContain("cg_crawl_logs.list");
+        expect(queries).toContain("cg_crawl_logs.get");
+        expect(queries).toContain("cg_digests.list");
+        expect(queries).toContain("cg_digests.get");
+        expect(queries).toContain("cg_app_settings.list");
+        expect(queries).toContain("cg_app_settings.get");
+    });
+
+    it("4개 테이블의 create/update/remove mutation이 모두 레지스트리에 등록된다", () => {
+        const mutations = getRegisteredMutations();
+        const names = mutations.map((m) => m.name);
+
+        // 각 테이블의 create + update + remove = 12개
+        expect(names).toContain("cg_keywords.create");
+        expect(names).toContain("cg_keywords.update");
+        expect(names).toContain("cg_keywords.remove");
+        expect(names).toContain("cg_crawl_logs.create");
+        expect(names).toContain("cg_crawl_logs.update");
+        expect(names).toContain("cg_crawl_logs.remove");
+        expect(names).toContain("cg_digests.create");
+        expect(names).toContain("cg_digests.update");
+        expect(names).toContain("cg_digests.remove");
+        expect(names).toContain("cg_app_settings.create");
+        expect(names).toContain("cg_app_settings.update");
+        expect(names).toContain("cg_app_settings.remove");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 2. crud() + 수동 query/mutation 혼용 — 양쪽 모두 codegen에 포함
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("crud() + 수동 query/mutation 혼용", () => {
+    beforeAll(() => {
+        // crud로 자동 등록
+        const articlesTable = pgTable("cg_articles", {
+            id: serial("id").primaryKey(),
+            title: text("title"),
+            createdAt: timestamp("created_at").defaultNow(),
+        });
+        crud(articlesTable, { public: true });
+
+        // 수동으로 추가 등록 (test032의 digestsModule.generate 패턴)
+        query("cg_digests.latest", {
+            public: true,
+            handler: async (ctx) => {
+                return { id: 1, title: "latest" };
+            },
+        });
+
+        mutation("cg_digests.generate", {
+            invalidates: ["cg_digests.list"],
+            public: true,
+            handler: async (ctx) => {
+                return { success: true };
+            },
+        });
+    });
+
+    it("crud 등록 + 수동 등록이 모두 getRegisteredQueries()에 포함된다", () => {
+        const queries = getRegisteredQueries();
+
+        // crud 자동 등록
+        expect(queries).toContain("cg_articles.list");
+        expect(queries).toContain("cg_articles.get");
+
+        // 수동 등록
+        expect(queries).toContain("cg_digests.latest");
+    });
+
+    it("crud 등록 + 수동 등록이 모두 getRegisteredMutations()에 포함된다", () => {
+        const mutations = getRegisteredMutations();
+        const names = mutations.map((m) => m.name);
+
+        // crud 자동 등록
+        expect(names).toContain("cg_articles.create");
+        expect(names).toContain("cg_articles.update");
+        expect(names).toContain("cg_articles.remove");
+
+        // 수동 등록
+        expect(names).toContain("cg_digests.generate");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 3. public/private 상태 정확성 — codegen이 isPublic 기반으로 auth 분기
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("crud() isPublic 상태 — codegen auth 분기 정확성", () => {
+    beforeAll(() => {
+        const publicTable = pgTable("cg_public_data", {
+            id: serial("id").primaryKey(),
+            name: text("name"),
+        });
+        const privateTable = pgTable("cg_private_data", {
+            id: serial("id").primaryKey(),
+            name: text("name"),
+        });
+
+        crud(publicTable, { public: true });
+        crud(privateTable); // default: auth 필수
+    });
+
+    it("public: true 테이블의 모든 엔드포인트가 isPublic === true", () => {
+        const listDef = getQueryDef("cg_public_data.list");
+        const getDef = getQueryDef("cg_public_data.get");
+
+        expect(listDef!.isPublic).toBe(true);
+        expect(getDef!.isPublic).toBe(true);
+
+        const mutations = getRegisteredMutations();
+        const createDef = mutations.find((m) => m.name === "cg_public_data.create");
+        expect(createDef!.isPublic).toBe(true);
+    });
+
+    it("기본(private) 테이블의 모든 엔드포인트가 isPublic === false", () => {
+        const listDef = getQueryDef("cg_private_data.list");
+        const getDef = getQueryDef("cg_private_data.get");
+
+        expect(listDef!.isPublic).toBe(false);
+        expect(getDef!.isPublic).toBe(false);
+
+        const mutations = getRegisteredMutations();
+        const createDef = mutations.find((m) => m.name === "cg_private_data.create");
+        expect(createDef!.isPublic).toBe(false);
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 4. codegen 시뮬레이션 — getRegisteredQueries/Mutations로 api.ts 생성
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("codegen 시뮬레이션 — api.ts 생성 가능 여부", () => {
+    it("getRegisteredQueries()로 모든 query key를 열거할 수 있다", () => {
+        const queries = getRegisteredQueries();
+        expect(queries.length).toBeGreaterThan(0);
+
+        // 모든 query key가 "namespace.action" 패턴이어야 함
+        for (const key of queries) {
+            expect(key).toMatch(/^[a-z_]+\.[a-z_]+$/i);
+        }
+    });
+
+    it("getRegisteredMutations()로 모든 mutation을 열거할 수 있다", () => {
+        const mutations = getRegisteredMutations();
+        expect(mutations.length).toBeGreaterThan(0);
+
+        // 모든 mutation이 name + handler를 가져야 함
+        for (const mut of mutations) {
+            expect(mut.name).toBeTruthy();
+            expect(typeof mut.handler).toBe("function");
+        }
+    });
+
+    it("getQueryDef()로 개별 query의 argsSchema에 접근할 수 있다", () => {
+        const listDef = getQueryDef("cg_keywords.list");
+        expect(listDef).toBeDefined();
+        // list handler에는 argsSchema가 있음 (limit, offset, sort, filters)
+        expect(listDef!.handler).toBeDefined();
+    });
+
+    it("codegen 대상 query/mutation 총 개수가 올바르다", () => {
+        const queries = getRegisteredQueries();
+        const mutations = getRegisteredMutations();
+
+        // 최소 8개 query (4테이블 × list+get) + 수동 1개 + 이전 테스트들
+        expect(queries.length).toBeGreaterThanOrEqual(8);
+        // 최소 12개 mutation (4테이블 × create+update+remove) + 수동 1개
+        expect(mutations.length).toBeGreaterThanOrEqual(12);
+    });
+});