reltype 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -6,7 +6,87 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
-## [0.1.0] — 2025-03-19
+## [0.1.5] — 2026-03-19
+
+### Changed
+- `README.md` — 전체 문서 최신 API 기준으로 업데이트
+- `README.ko.md` — 한국어 문서 최신 API 기준으로 업데이트
+- `CHANGELOG.md` — 0.1.1 ~ 0.1.4 릴리즈 내역 소급 작성
+
+---
+
+## [0.1.4] — 2026-03-19
+
+### Changed
+- `package.json` / `package-lock.json` — 버전 범프 (0.1.3 → 0.1.4)
+
+---
+
+## [0.1.3] — 2026-03-19
+
+### Fixed (refactor: type info)
+
+#### Query Guard — 빈 입력 방어 로직 추가
+- `buildInsert` — 삽입할 데이터가 없을 때 `logger.error` 출력 후 no-op 반환
+- `buildUpdate` — 수정 데이터 없음 / WHERE 조건 없음 각각 감지 후 no-op 반환 (전체 업데이트 방지)
+- `buildDelete` — WHERE 조건 없음 감지 후 no-op 반환 (전체 삭제 방지), `RETURNING *` 추가
+- `buildUpsert` — 삽입 데이터 없음 감지 후 no-op 반환, 충돌 컬럼만 있을 경우 `DO NOTHING` 처리
+- `buildBulkInsert` — 빈 배열 및 첫 row 데이터 없음 감지 후 no-op 반환
+
+#### QueryBuilder — 안정성 개선
+- `one()` — `this._limitVal` 직접 변이 제거 → `clone()`으로 원본 불변 처리
+- `paginate()` — `Promise.all` 제거, 같은 클라이언트에서 COUNT → DATA 순차 실행
+- `cursorPaginate()` — 잘못된 cursor 토큰 시 `logger.error` 출력 후 빈 결과 반환 (cursor 값 메시지 노출 제거)
+- `clone()` — `_execHooks` 복사 누락 수정
+
+#### BaseRepo — 일관성 개선
+- `exec()` — 빈 SQL 진입 시 `logger.error` 후 즉시 `[]` 반환 (no-op 계층 추가)
+- `delete()` — 내부 `withClient` 직접 호출 제거, `exec()` 재사용으로 로깅 일관성 확보
+- `selectOne()` — 글로벌 훅(`useHooks`) 자동 적용되도록 수정 (`this.select(where).one()` 위임)
+- `findPkKey()` — primary key 미정의 시 조용한 fallback 대신 `logger.warn` 출력
+
+#### Schema / Column
+- `Col` — `isDefaultNow: boolean` 필드 추가로 `default()` / `defaultNow()` 의미 구분
+- `Col.nullable()` / `notNull()` / `primaryKey()` — `isDefaultNow` 상태 올바르게 전파
+- `toSnake()` — 두문자어(Acronym) 처리 개선 (정규식 2단계 적용)
+  - `URLParam` → `url_param` ✓ / `userID` → `user_id` ✓
+
+#### Connection Pool
+- `PoolStatus` — `isInitialized: boolean` 필드 추가
+- `getPoolStatus()` — pool 미초기화 시 `isHealthy: false` 반환 (이전: `true`)
+- `readPoolStatus()` — `isHealthy` 조건 개선: `!(waitingCount > 0 && idleCount === 0)` (pool 소진 상태만 unhealthy)
+
+#### Package
+- `dotenv` — `dependencies` → `devDependencies` 이동 (라이브러리 소비자 의존성 오염 방지)
+
+---
+
+## [0.1.2] — 2026-03-19
+
+### Changed
+- `package.json` / `package-lock.json` — 버전 범프 (0.1.1 → 0.1.2)
+
+---
+
+## [0.1.1] — 2026-03-19
+
+### Added (feat: add schema selection for database connection)
+- `defineTable` — PostgreSQL 스키마 지원 추가
+  - `defineTable('audit.activity_logs', cols)` — dot 표기법
+  - `defineTable('users', cols, { schema: 'auth' })` — 명시적 옵션
+  - `qualifiedName` 자동 생성 (`"auth"."users"` 형태로 SQL 식별자 인용)
+- `TableOpts` 인터페이스 추가 (`{ schema?: string }`)
+- `TableDef` — `qualifiedName` 필드 추가
+- `src/index.ts` — `TableOpts` re-export 추가
+
+### Changed
+- `package.json` — `pg` → `peerDependencies` 이동, `express` / `nodemon` / `typescript` → `devDependencies` 이동
+- `main`, `types`, `exports`, `files`, `keywords`, `repository`, `engines` 필드 추가로 npm 배포 최적화
+- `scripts` — `typecheck`, `prepublishOnly` 추가
+
+---
+
+## [0.1.0] — 2026-03-19
 
 ### Added
 
@@ -22,7 +102,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 - `.exec()` — 쿼리 실행 → `T[]`
 - `.one()` — 단건 실행 → `T | null`
 - `.calculate(fns)` — COUNT / SUM / AVG / MIN / MAX 집계
-- `.paginate(opts)` — OFFSET 기반 페이지네이션 (COUNT + DATA 병렬 실행)
+- `.paginate(opts)` — OFFSET 기반 페이지네이션
 - `.toSQL()` — 생성될 SQL 미리 확인 (디버깅용)
 - `QueryBuilder.raw(sql, params?)` — 독립 Raw SQL 실행
 
@@ -53,7 +133,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
-## [0.0.1] — Initial Release
+## [0.0.1] — 2026-02-13
 
 ### Added
 - `defineTable` / `col` — 테이블 스키마 정의 및 타입 추론 (`InferRow`, `InferInsert`, `InferUpdate`)

package/dist/features/connection/pool.d.ts

@@ -1,13 +1,20 @@
 import { Pool, PoolClient, PoolConfig } from 'pg';
 /** Pool 상태 스냅샷 */
 export interface PoolStatus {
+    /** Pool이 초기화되어 있는지 여부 */
+    isInitialized: boolean;
     /** 총 생성된 연결 수 */
     totalCount: number;
     /** 현재 유휴 연결 수 */
     idleCount: number;
     /** 연결 대기 중인 요청 수 */
     waitingCount: number;
-    /** Pool이 정상 상태인지 여부 */
+    /**
+     * Pool이 정상 상태인지 여부.
+     * - `isInitialized === false` → false
+     * - `waitingCount > 0 && idleCount === 0` → false (pool 소진)
+     * - 그 외 → true
+     */
     isHealthy: boolean;
 }
 /**

package/dist/features/connection/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../../src/features/connection/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAUlD,kBAAkB;AAClB,MAAM,WAAW,UAAU;IACzB,iBAAiB;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAOD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAuDjD;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAK1C;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CASxD;AAED;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAM/C"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../../src/features/connection/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAUlD,kBAAkB;AAClB,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAOD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAuDjD;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAW1C;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CASxD;AAED;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAM/C"}

package/dist/features/connection/pool.js

@@ -91,7 +91,13 @@ async function withClient(fn) {
  */
 function getPoolStatus() {
     if (!_pool) {
-        return { totalCount: 0, idleCount: 0, waitingCount: 0, isHealthy: true };
+        return {
+            isInitialized: false,
+            totalCount: 0,
+            idleCount: 0,
+            waitingCount: 0,
+            isHealthy: false,
+        };
     }
     return readPoolStatus(_pool);
 }
@@ -122,10 +128,13 @@ async function closePool() {
     logger.info('Pool 종료 완료');
 }
 function readPoolStatus(pool) {
+    const { totalCount, idleCount, waitingCount } = pool;
     return {
-        totalCount: pool.totalCount,
-        idleCount: pool.idleCount,
-        waitingCount: pool.waitingCount,
-        isHealthy: pool.idleCount > 0 || pool.waitingCount === 0,
+        isInitialized: true,
+        totalCount,
+        idleCount,
+        waitingCount,
+        // pool이 소진된 경우(대기 요청이 있는데 유휴 연결이 없음)에만 unhealthy
+        isHealthy: !(waitingCount > 0 && idleCount === 0),
     };
 }

package/dist/features/query/builder.d.ts

@@ -72,8 +72,12 @@ export declare class QueryBuilder<T extends Record<string, unknown>> {
     groupBy(columns: Array<keyof T | string>): this;
     /**
      * JOIN 추가 (여러 번 호출 가능)
+     *
      * @example
      * .join({ table: 'orders', on: 'users.id = orders.user_id', type: 'LEFT' })
+     *
+     * @security `on` 절은 애플리케이션 코드에서 정적으로 구성해야 합니다.
+     *           사용자 입력을 직접 전달하면 SQL Injection 위험이 있습니다.
      */
     join(j: JoinClause): this;
     /**
@@ -83,6 +87,7 @@ export declare class QueryBuilder<T extends Record<string, unknown>> {
     columns(cols: Array<keyof T | string>): this;
     /**
      * 쿼리 실행 라이프사이클 훅을 등록합니다.
+     * 전역 훅(`useHooks`)이 설정되어 있으면 per-query 훅이 우선합니다.
      *
      * @example
      * ```ts
@@ -103,6 +108,7 @@ export declare class QueryBuilder<T extends Record<string, unknown>> {
     exec(): Promise<T[]>;
     /**
      * 첫 번째 row 하나를 반환합니다. 없으면 null입니다.
+     * 내부적으로 clone()을 사용하여 원본 builder 상태를 변경하지 않습니다.
      */
     one(): Promise<T | null>;
     /**
@@ -121,7 +127,7 @@ export declare class QueryBuilder<T extends Record<string, unknown>> {
     calculate(fns: AggregateCalc[]): Promise<Record<string, unknown>>;
     /**
      * OFFSET 기반 페이지네이션.
-     * COUNT + DATA 쿼리를 병렬로 실행합니다.
+     * COUNT + DATA 쿼리를 같은 트랜잭션 안에서 순차 실행합니다.
      *
      * > 수백만 건 이상의 테이블에서는 `cursorPaginate()`를 사용하세요.
      *
@@ -161,7 +167,7 @@ export declare class QueryBuilder<T extends Record<string, unknown>> {
      *
      * 대용량 테이블의 일괄 처리(ETL, 이메일 발송, 마이그레이션 등)에 적합합니다.
      *
-     * @param fn        - 배치 배열을 받아 처리하는 비동기 함수
+     * @param fn             - 배치 배열을 받아 처리하는 비동기 함수
      * @param opts.batchSize - 한 번에 처리할 row 수 (기본값: 500)
      *
      * @example
@@ -235,7 +241,8 @@ export declare class QueryBuilder<T extends Record<string, unknown>> {
     static raw<R extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<R[]>;
     /**
      * builder 상태를 독립적으로 복사합니다.
-     * stream/forEach 내부에서 LIMIT/OFFSET을 덮어쓸 때 원본을 보호하기 위해 사용합니다.
+     * `one()`, `cursorPaginate()`, `stream()`, `forEach()` 내부에서
+     * LIMIT/OFFSET 등 상태를 임시 변경할 때 원본을 보호하기 위해 사용합니다.
      */
     clone(): QueryBuilder<T>;
     then<R>(onfulfilled: ((value: T[]) => R | PromiseLike<R>) | null | undefined, onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null | undefined): Promise<R>;

package/dist/features/query/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/features/query/builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/features/query/builder.ts"],"names":[],"mappings":"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"}

package/dist/features/query/builder.js

@@ -145,8 +145,12 @@ class QueryBuilder {
     }
     /**
      * JOIN 추가 (여러 번 호출 가능)
+     *
      * @example
      * .join({ table: 'orders', on: 'users.id = orders.user_id', type: 'LEFT' })
+     *
+     * @security `on` 절은 애플리케이션 코드에서 정적으로 구성해야 합니다.
+     *           사용자 입력을 직접 전달하면 SQL Injection 위험이 있습니다.
      */
     join(j) {
         this._joins.push(j);
@@ -162,6 +166,7 @@ class QueryBuilder {
     }
     /**
      * 쿼리 실행 라이프사이클 훅을 등록합니다.
+     * 전역 훅(`useHooks`)이 설정되어 있으면 per-query 훅이 우선합니다.
      *
      * @example
      * ```ts
@@ -189,17 +194,11 @@ class QueryBuilder {
     }
     /**
      * 첫 번째 row 하나를 반환합니다. 없으면 null입니다.
+     * 내부적으로 clone()을 사용하여 원본 builder 상태를 변경하지 않습니다.
      */
     async one() {
-        const saved = this._limitVal;
-        this._limitVal = 1;
-        try {
-            const rows = await this.exec();
-            return rows[0] ?? null;
-        }
-        finally {
-            this._limitVal = saved;
-        }
+        const rows = await this.clone().limit(1).exec();
+        return rows[0] ?? null;
     }
     /**
      * 집계 함수를 실행합니다.
@@ -233,7 +232,7 @@ class QueryBuilder {
     }
     /**
      * OFFSET 기반 페이지네이션.
-     * COUNT + DATA 쿼리를 병렬로 실행합니다.
+     * COUNT + DATA 쿼리를 같은 트랜잭션 안에서 순차 실행합니다.
      *
      * > 수백만 건 이상의 테이블에서는 `cursorPaginate()`를 사용하세요.
      *
@@ -254,32 +253,32 @@ class QueryBuilder {
             `SELECT COUNT(*) AS count FROM ${this._table}`,
             joinSQL, whereSQL, groupSQL,
         ].filter(Boolean).join(' ');
-        const dataParams = [...whereParams];
-        dataParams.push(pageSize);
-        const limitIdx = dataParams.length;
-        dataParams.push((page - 1) * pageSize);
-        const offsetIdx = dataParams.length;
+        // LIMIT/OFFSET 파라미터를 whereParams 뒤에 이어붙임
+        const dataParams = [...whereParams, pageSize, (page - 1) * pageSize];
+        const limitIdx = whereParams.length + 1;
+        const offsetIdx = whereParams.length + 2;
         const dataSql = [
             `SELECT ${this._cols} FROM ${this._table}`,
             joinSQL, whereSQL, groupSQL, orderSQL,
             `LIMIT $${limitIdx} OFFSET $${offsetIdx}`,
         ].filter(Boolean).join(' ');
         try {
+            // 같은 클라이언트로 순차 실행하여 커넥션 절약
             return await (0, pool_1.withClient)(async (client) => {
                 if (this._execHooks?.beforeExec) {
                     await this._execHooks.beforeExec({ sql: dataSql, params: dataParams });
                 }
                 const start = Date.now();
-                logger.debug(`COUNT SQL: ${countSql}`, whereParams);
-                logger.debug(`DATA  SQL: ${dataSql}`, dataParams);
-                const [countResult, dataResult] = await Promise.all([
-                    client.query(countSql, whereParams),
-                    client.query(dataSql, dataParams),
-                ]);
+                logger.debug(`PAGINATE COUNT SQL: ${countSql}`, whereParams);
+                logger.debug(`PAGINATE DATA  SQL: ${dataSql}`, dataParams);
+                const countResult = await client.query(countSql, whereParams);
+                const dataResult = await client.query(dataSql, dataParams);
                 const total = parseInt(String(countResult.rows[0].count ?? '0'), 10);
                 const data = (0, mapper_1.mapRows)(dataResult.rows);
+                const elapsed = Date.now() - start;
+                logger.debug(`PAGINATE 완료 (${elapsed}ms) total=${total}`);
                 if (this._execHooks?.afterExec) {
-                    await this._execHooks.afterExec({ rows: data, elapsed: Date.now() - start, sql: dataSql });
+                    await this._execHooks.afterExec({ rows: data, elapsed, sql: dataSql });
                 }
                 return {
                     data,
@@ -324,17 +323,17 @@ class QueryBuilder {
     async cursorPaginate(opts) {
         const { pageSize, cursor, cursorColumn, direction = 'asc' } = opts;
         const colSnake = (0, case_1.toSnake)(cursorColumn);
-        // 커서 값 디코딩
         let cursorValue;
         if (cursor) {
             try {
                 cursorValue = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
             }
             catch {
-                throw new Error(`유효하지 않은 cursor 값입니다: ${cursor}`);
+                logger.error(`cursorPaginate [${this._table}]: 유효하지 않은 cursor 토큰입니다. 이전 페이지 응답의 nextCursor 값을 그대로 사용하세요.`);
+                return { data: [], nextCursor: null, pageSize, hasNext: false };
             }
         }
-        // 기존 조건에 커서 조건 추가 (원본 builder를 변경하지 않음)
+        // 원본 builder를 변경하지 않고 clone으로 처리
         const qb = this.clone();
         if (cursorValue !== undefined) {
             qb._andConds.push({
@@ -349,7 +348,6 @@ class QueryBuilder {
         const rows = await qb.exec();
         const hasNext = rows.length > pageSize;
         const data = hasNext ? rows.slice(0, pageSize) : rows;
-        // 다음 커서 인코딩 (마지막 row의 cursorColumn 값)
         let nextCursor = null;
         if (hasNext && data.length > 0) {
             const lastRow = data[data.length - 1];
@@ -363,7 +361,7 @@ class QueryBuilder {
      *
      * 대용량 테이블의 일괄 처리(ETL, 이메일 발송, 마이그레이션 등)에 적합합니다.
      *
-     * @param fn        - 배치 배열을 받아 처리하는 비동기 함수
+     * @param fn             - 배치 배열을 받아 처리하는 비동기 함수
      * @param opts.batchSize - 한 번에 처리할 row 수 (기본값: 500)
      *
      * @example
@@ -499,7 +497,8 @@ class QueryBuilder {
     }
     /**
      * builder 상태를 독립적으로 복사합니다.
-     * stream/forEach 내부에서 LIMIT/OFFSET을 덮어쓸 때 원본을 보호하기 위해 사용합니다.
+     * `one()`, `cursorPaginate()`, `stream()`, `forEach()` 내부에서
+     * LIMIT/OFFSET 등 상태를 임시 변경할 때 원본을 보호하기 위해 사용합니다.
      */
     clone() {
         const c = new QueryBuilder(this._table);

package/dist/features/query/bulkInsert.d.ts

@@ -1,10 +1,13 @@
 import { BuiltQuery } from './interfaces/Query';
 /**
  * 여러 row를 한 번의 INSERT 쿼리로 삽입합니다.
- * 빈 배열이 전달되면 빈 BuiltQuery를 반환합니다.
  *
- * @param table - 테이블명 (snake_case)
- * @param rows  - 삽입할 데이터 배열 (camelCase key, 모든 row는 동일한 key 구조여야 합니다)
+ * @param table - 테이블명
+ * @param rows  - 삽입할 데이터 배열 (camelCase key)
+ *               모든 row가 동일한 key 구조를 가져야 합니다.
+ *               첫 번째 row의 key 목록을 기준으로 컬럼을 결정합니다.
+ *
+ * rows가 빈 배열이거나 첫 row의 데이터가 없으면 빈 쿼리를 반환합니다 (실행 시 no-op).
  */
 export declare function buildBulkInsert(table: string, rows: Record<string, unknown>[]): BuiltQuery;
 //# sourceMappingURL=bulkInsert.d.ts.map

package/dist/features/query/bulkInsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bulkInsert.d.ts","sourceRoot":"","sources":["../../../src/features/query/bulkInsert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAC9B,UAAU,CAqBZ"}
+{"version":3,"file":"bulkInsert.d.ts","sourceRoot":"","sources":["../../../src/features/query/bulkInsert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQhD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAC9B,UAAU,CA4BZ"}

package/dist/features/query/bulkInsert.js

@@ -2,23 +2,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildBulkInsert = buildBulkInsert;
 const case_1 = require("../transform/case");
+const logger_1 = require("../../utils/logger");
+const logger = logger_1.Logger.fromEnv(process.env, { prefix: '[Query]' });
 /**
  * 여러 row를 한 번의 INSERT 쿼리로 삽입합니다.
- * 빈 배열이 전달되면 빈 BuiltQuery를 반환합니다.
  *
- * @param table - 테이블명 (snake_case)
- * @param rows  - 삽입할 데이터 배열 (camelCase key, 모든 row는 동일한 key 구조여야 합니다)
+ * @param table - 테이블명
+ * @param rows  - 삽입할 데이터 배열 (camelCase key)
+ *               모든 row가 동일한 key 구조를 가져야 합니다.
+ *               첫 번째 row의 key 목록을 기준으로 컬럼을 결정합니다.
+ *
+ * rows가 빈 배열이거나 첫 row의 데이터가 없으면 빈 쿼리를 반환합니다 (실행 시 no-op).
  */
 function buildBulkInsert(table, rows) {
     if (rows.length === 0) {
+        logger.error(`buildBulkInsert [${table}]: 삽입할 row가 없습니다.`);
         return { sql: '', params: [] };
     }
     const keys = Object.keys(rows[0]).filter((k) => rows[0][k] !== undefined);
+    if (keys.length === 0) {
+        logger.error(`buildBulkInsert [${table}]: 첫 번째 row에 삽입할 데이터가 없습니다.`);
+        return { sql: '', params: [] };
+    }
     const cols = keys.map(case_1.toSnake).join(', ');
     const params = [];
     const valueSets = rows.map((row) => {
         const placeholders = keys.map((k) => {
-            params.push(row[k]);
+            params.push(row[k] ?? null);
             return `$${params.length}`;
         });
         return `(${placeholders.join(', ')})`;

package/dist/features/query/delete.d.ts

@@ -1,8 +1,10 @@
 import { BuiltQuery } from './interfaces/Query';
 import { WhereInput } from './interfaces/Where';
 /**
- * DELETE 쿼리를 생성합니다.
+ * DELETE 쿼리를 생성합니다. RETURNING * 으로 삭제된 row를 반환합니다.
  * camelCase key → snake_case 컬럼명으로 자동 변환됩니다.
+ *
+ * WHERE 조건이 없으면 빈 쿼리를 반환합니다 (전체 삭제 방지, 실행 시 no-op).
  */
 export declare function buildDelete<T extends Record<string, unknown>>(table: string, where: WhereInput<T>): BuiltQuery;
 //# sourceMappingURL=delete.d.ts.map

package/dist/features/query/delete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../src/features/query/delete.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GACnB,UAAU,CAOZ"}
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../src/features/query/delete.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQhD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GACnB,UAAU,CAcZ"}

package/dist/features/query/delete.js

@@ -2,14 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildDelete = buildDelete;
 const where_1 = require("./where");
+const logger_1 = require("../../utils/logger");
+const logger = logger_1.Logger.fromEnv(process.env, { prefix: '[Query]' });
 /**
- * DELETE 쿼리를 생성합니다.
+ * DELETE 쿼리를 생성합니다. RETURNING * 으로 삭제된 row를 반환합니다.
  * camelCase key → snake_case 컬럼명으로 자동 변환됩니다.
+ *
+ * WHERE 조건이 없으면 빈 쿼리를 반환합니다 (전체 삭제 방지, 실행 시 no-op).
  */
 function buildDelete(table, where) {
+    const whereEntries = Object.entries(where).filter(([, v]) => v !== undefined);
+    if (whereEntries.length === 0) {
+        logger.error(`buildDelete [${table}]: WHERE 조건이 없습니다. 전체 행 삭제를 방지합니다.`);
+        return { sql: '', params: [] };
+    }
     const { sql: whereSql, params } = (0, where_1.buildWhere)(where);
     return {
-        sql: [`DELETE FROM ${table}`, whereSql].filter(Boolean).join(' '),
+        sql: [`DELETE FROM ${table}`, whereSql, 'RETURNING *'].filter(Boolean).join(' '),
         params,
     };
 }

package/dist/features/query/insert.d.ts

@@ -2,6 +2,8 @@ import { BuiltQuery } from './interfaces/Query';
 /**
  * INSERT 쿼리를 생성합니다. RETURNING * 으로 삽입된 row를 반환합니다.
  * camelCase key → snake_case 컬럼명으로 자동 변환됩니다.
+ *
+ * 삽입할 데이터가 없으면 빈 쿼리를 반환합니다 (실행 시 no-op).
  */
 export declare function buildInsert(table: string, data: Record<string, unknown>): BuiltQuery;
 //# sourceMappingURL=insert.d.ts.map

package/dist/features/query/insert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../src/features/query/insert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,UAAU,CAWZ"}
+{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../src/features/query/insert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQhD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,UAAU,CAgBZ"}

package/dist/features/query/insert.js

@@ -2,12 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildInsert = buildInsert;
 const case_1 = require("../transform/case");
+const logger_1 = require("../../utils/logger");
+const logger = logger_1.Logger.fromEnv(process.env, { prefix: '[Query]' });
 /**
  * INSERT 쿼리를 생성합니다. RETURNING * 으로 삽입된 row를 반환합니다.
  * camelCase key → snake_case 컬럼명으로 자동 변환됩니다.
+ *
+ * 삽입할 데이터가 없으면 빈 쿼리를 반환합니다 (실행 시 no-op).
  */
 function buildInsert(table, data) {
     const entries = Object.entries(data).filter(([, v]) => v !== undefined);
+    if (entries.length === 0) {
+        logger.error(`buildInsert [${table}]: 삽입할 데이터가 없습니다.`);
+        return { sql: '', params: [] };
+    }
     const cols = entries.map(([k]) => (0, case_1.toSnake)(k)).join(', ');
     const placeholders = entries.map((_, i) => `$${i + 1}`).join(', ');
     const params = entries.map(([, v]) => v);

package/dist/features/query/update.d.ts

@@ -3,6 +3,8 @@ import { WhereInput } from './interfaces/Where';
 /**
  * UPDATE 쿼리를 생성합니다. RETURNING * 으로 수정된 row를 반환합니다.
  * camelCase key → snake_case 컬럼명으로 자동 변환됩니다.
+ *
+ * 수정할 데이터가 없거나 WHERE 조건이 없으면 빈 쿼리를 반환합니다 (실행 시 no-op).
  */
 export declare function buildUpdate<T extends Record<string, unknown>>(table: string, data: Partial<T>, where: WhereInput<T>): BuiltQuery;
 //# sourceMappingURL=update.d.ts.map

package/dist/features/query/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/features/query/update.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GACnB,UAAU,CAsBZ"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/features/query/update.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQhD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GACnB,UAAU,CAiCZ"}

package/dist/features/query/update.js

@@ -3,12 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildUpdate = buildUpdate;
 const case_1 = require("../transform/case");
 const where_1 = require("./where");
+const logger_1 = require("../../utils/logger");
+const logger = logger_1.Logger.fromEnv(process.env, { prefix: '[Query]' });
 /**
  * UPDATE 쿼리를 생성합니다. RETURNING * 으로 수정된 row를 반환합니다.
  * camelCase key → snake_case 컬럼명으로 자동 변환됩니다.
+ *
+ * 수정할 데이터가 없거나 WHERE 조건이 없으면 빈 쿼리를 반환합니다 (실행 시 no-op).
  */
 function buildUpdate(table, data, where) {
     const entries = Object.entries(data).filter(([, v]) => v !== undefined);
+    const whereEntries = Object.entries(where).filter(([, v]) => v !== undefined);
+    if (entries.length === 0) {
+        logger.error(`buildUpdate [${table}]: 수정할 데이터가 없습니다.`);
+        return { sql: '', params: [] };
+    }
+    if (whereEntries.length === 0) {
+        logger.error(`buildUpdate [${table}]: WHERE 조건이 없습니다. 전체 행 업데이트를 방지합니다.`);
+        return { sql: '', params: [] };
+    }
     const params = [];
     const setClauses = entries.map(([k, v]) => {
         params.push(v);

package/dist/features/query/upsert.d.ts

@@ -3,9 +3,11 @@ import { BuiltQuery } from './interfaces/Query';
  * INSERT ... ON CONFLICT DO UPDATE 쿼리를 생성합니다.
  * 충돌 컬럼을 제외한 나머지 컬럼을 EXCLUDED 값으로 업데이트합니다.
  *
- * @param table       - 테이블명 (snake_case)
+ * @param table       - 테이블명
  * @param data        - 삽입할 데이터 (camelCase key)
  * @param conflictCol - 충돌 기준 컬럼명 (snake_case)
+ *
+ * 삽입할 데이터가 없으면 빈 쿼리를 반환합니다 (실행 시 no-op).
  */
 export declare function buildUpsert(table: string, data: Record<string, unknown>, conflictCol: string): BuiltQuery;
 //# sourceMappingURL=upsert.d.ts.map

package/dist/features/query/upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/features/query/upsert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE,MAAM,GAClB,UAAU,CAqBZ"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/features/query/upsert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQhD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE,MAAM,GAClB,UAAU,CAqCZ"}

package/dist/features/query/upsert.js

@@ -2,16 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildUpsert = buildUpsert;
 const case_1 = require("../transform/case");
+const logger_1 = require("../../utils/logger");
+const logger = logger_1.Logger.fromEnv(process.env, { prefix: '[Query]' });
 /**
  * INSERT ... ON CONFLICT DO UPDATE 쿼리를 생성합니다.
  * 충돌 컬럼을 제외한 나머지 컬럼을 EXCLUDED 값으로 업데이트합니다.
  *
- * @param table       - 테이블명 (snake_case)
+ * @param table       - 테이블명
  * @param data        - 삽입할 데이터 (camelCase key)
  * @param conflictCol - 충돌 기준 컬럼명 (snake_case)
+ *
+ * 삽입할 데이터가 없으면 빈 쿼리를 반환합니다 (실행 시 no-op).
  */
 function buildUpsert(table, data, conflictCol) {
     const entries = Object.entries(data).filter(([, v]) => v !== undefined);
+    if (entries.length === 0) {
+        logger.error(`buildUpsert [${table}]: 삽입할 데이터가 없습니다.`);
+        return { sql: '', params: [] };
+    }
     const cols = entries.map(([k]) => (0, case_1.toSnake)(k)).join(', ');
     const placeholders = entries.map((_, i) => `$${i + 1}`).join(', ');
     const params = entries.map(([, v]) => v);
@@ -20,6 +28,16 @@ function buildUpsert(table, data, conflictCol) {
         .filter((col) => col !== conflictCol)
         .map((col) => `${col} = EXCLUDED.${col}`)
         .join(', ');
+    if (!updateSet) {
+        return {
+            sql: [
+                `INSERT INTO ${table} (${cols}) VALUES (${placeholders})`,
+                `ON CONFLICT (${conflictCol}) DO NOTHING`,
+                'RETURNING *',
+            ].join(' '),
+            params,
+        };
+    }
     return {
         sql: [
             `INSERT INTO ${table} (${cols}) VALUES (${placeholders})`,

package/dist/features/repository/base.d.ts

@@ -44,6 +44,10 @@ export declare class BaseRepo<TDef extends TableDef<string, Cols>> implements IR
     findOne(where: Partial<InferRow<TDef>>): Promise<InferRow<TDef> | null>;
     create(data: InferInsert<TDef>): Promise<InferRow<TDef>>;
     update(id: number | string, data: InferUpdate<TDef>): Promise<InferRow<TDef> | null>;
+    /**
+     * ID로 단건 삭제합니다.
+     * `exec()`를 재사용하여 로깅과 에러 처리를 일관성 있게 처리합니다.
+     */
     delete(id: number | string): Promise<boolean>;
     /**
      * 데이터를 삽입하거나, 충돌 시 UPDATE합니다.
@@ -52,41 +56,33 @@ export declare class BaseRepo<TDef extends TableDef<string, Cols>> implements IR
     upsert(data: InferInsert<TDef>, conflictCol?: string): Promise<InferRow<TDef>>;
     /**
      * 여러 row를 단일 INSERT 쿼리로 삽입합니다.
+     *
+     * @throws rows가 빈 배열이면 Error를 던집니다.
      */
     bulkCreate(rows: InferInsert<TDef>[]): Promise<InferRow<TDef>[]>;
     /**
      * 유연한 플루언트 쿼리 빌더를 반환합니다.
-     *
-     * WHERE, OR, ORDER BY, GROUP BY, JOIN, LIMIT, OFFSET, paginate, calculate 등을
-     * 메서드 체인으로 조합할 수 있습니다.
+     * 전역 훅(`useHooks`)이 설정된 경우 빌더에 자동으로 주입됩니다.
      *
      * @example
      * ```ts
-     * // 기본 조회 (await 직접 사용 가능)
      * const users = await repo.select({ isActive: true })
      *   .orderBy([{ column: 'createdAt', direction: 'DESC' }])
      *   .limit(20);
      *
-     * // OR 조건
-     * const results = await repo.select()
-     *   .or({ email: { operator: 'LIKE', value: '%@gmail.com' } });
-     *
-     * // 페이지네이션
      * const page = await repo.select()
      *   .paginate({ page: 1, pageSize: 20 });
-     *
-     * // 집계
-     * const agg = await repo.select({ isActive: true })
-     *   .calculate([{ fn: 'COUNT', alias: 'count' }]);
      * ```
      */
     select(where?: AdvancedWhere<InferRow<TDef>>): QueryBuilder<InferRow<TDef>>;
     /**
      * 단건 조회 (없으면 null). `select(where).one()` 의 단축형입니다.
+     * 전역 훅이 적용됩니다.
      *
      * @example
      * ```ts
      * const user = await repo.selectOne({ id: 1 });
+     * const user = await repo.selectOne({ email: 'foo@bar.com' });
      * ```
      */
     selectOne(where: AdvancedWhere<InferRow<TDef>>): Promise<InferRow<TDef> | null>;

package/dist/features/repository/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/features/repository/base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/features/repository/base.ts"],"names":[],"mappings":"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"}

package/dist/features/repository/base.js

@@ -14,10 +14,19 @@ const pool_1 = require("../connection/pool");
 const logger_1 = require("../../utils/logger");
 const dbError_1 = require("../../utils/dbError");
 const logger = logger_1.Logger.fromEnv(process.env, { prefix: '[Repo]' });
-/** 런타임에서 primary key의 camelCase 키를 찾습니다. */
-function findPkKey(cols) {
+/**
+ * 런타임에서 primary key의 camelCase 키를 찾습니다.
+ * primary key가 없으면 경고를 출력하고 'id'를 기본값으로 사용합니다.
+ */
+function findPkKey(cols, tableName) {
     const entry = Object.entries(cols).find(([, c]) => c.isPrimary);
-    return entry ? entry[0] : 'id';
+    if (!entry) {
+        logger.warn(`[Repo] '${tableName}' 테이블에 primary key가 정의되지 않았습니다. ` +
+            `findById, delete 등에서 'id' 컬럼을 기본값으로 사용합니다. ` +
+            `col.xxx().primaryKey() 로 명시적으로 지정하세요.`);
+        return 'id';
+    }
+    return entry[0];
 }
 /**
  * 기본 CRUD 레포지토리.
@@ -29,9 +38,8 @@ function findPkKey(cols) {
 class BaseRepo {
     constructor(def) {
         this.def = def;
-        // qualifiedName이 있으면 사용 ("schema"."table"), 없으면 name 사용
         this.tableName = def.qualifiedName ?? def.name;
-        this.pkKey = findPkKey(def.cols);
+        this.pkKey = findPkKey(def.cols, this.tableName);
         this.pkCol = (0, case_1.toSnake)(this.pkKey);
     }
     /**
@@ -56,6 +64,10 @@ class BaseRepo {
      * - `client`를 넘기면 해당 client를 재사용합니다 (트랜잭션 지원).
      */
     async exec(built, client) {
+        if (!built.sql) {
+            logger.error(`[${this.tableName}] 빈 SQL이 전달되었습니다. 실행을 건너뜁니다.`);
+            return [];
+        }
         const run = async (c) => {
             const start = Date.now();
             logger.debug(`SQL: ${built.sql}`, built.params);
@@ -126,27 +138,15 @@ class BaseRepo {
             throw dbError_1.DbError.from(err);
         }
     }
+    /**
+     * ID로 단건 삭제합니다.
+     * `exec()`를 재사용하여 로깅과 에러 처리를 일관성 있게 처리합니다.
+     */
     async delete(id) {
         try {
             const where = { [this.pkKey]: id };
-            const built = (0, delete_1.buildDelete)(this.tableName, where);
-            return await (0, pool_1.withClient)(async (client) => {
-                const start = Date.now();
-                logger.debug(`SQL: ${built.sql}`, built.params);
-                try {
-                    const result = await client.query(built.sql, built.params);
-                    logger.debug(`완료 (${Date.now() - start}ms)`);
-                    return (result.rowCount ?? 0) > 0;
-                }
-                catch (err) {
-                    const dbErr = dbError_1.DbError.from(err);
-                    logger.error(`삭제 실패 [${this.tableName}]`, {
-                        ...dbErr.toLogContext(),
-                        elapsed: `${Date.now() - start}ms`,
-                    });
-                    throw dbErr;
-                }
-            });
+            const rows = await this.exec((0, delete_1.buildDelete)(this.tableName, where));
+            return rows.length > 0;
         }
         catch (err) {
             throw dbError_1.DbError.from(err);
@@ -167,6 +167,8 @@ class BaseRepo {
     }
     /**
      * 여러 row를 단일 INSERT 쿼리로 삽입합니다.
+     *
+     * @throws rows가 빈 배열이면 Error를 던집니다.
      */
     async bulkCreate(rows) {
         try {
@@ -179,28 +181,16 @@ class BaseRepo {
     // ── Fluent QueryBuilder ────────────────────────────────────────────────────
     /**
      * 유연한 플루언트 쿼리 빌더를 반환합니다.
-     *
-     * WHERE, OR, ORDER BY, GROUP BY, JOIN, LIMIT, OFFSET, paginate, calculate 등을
-     * 메서드 체인으로 조합할 수 있습니다.
+     * 전역 훅(`useHooks`)이 설정된 경우 빌더에 자동으로 주입됩니다.
      *
      * @example
      * ```ts
-     * // 기본 조회 (await 직접 사용 가능)
      * const users = await repo.select({ isActive: true })
      *   .orderBy([{ column: 'createdAt', direction: 'DESC' }])
      *   .limit(20);
      *
-     * // OR 조건
-     * const results = await repo.select()
-     *   .or({ email: { operator: 'LIKE', value: '%@gmail.com' } });
-     *
-     * // 페이지네이션
      * const page = await repo.select()
      *   .paginate({ page: 1, pageSize: 20 });
-     *
-     * // 집계
-     * const agg = await repo.select({ isActive: true })
-     *   .calculate([{ fn: 'COUNT', alias: 'count' }]);
      * ```
      */
     select(where) {
@@ -211,15 +201,17 @@ class BaseRepo {
     }
     /**
      * 단건 조회 (없으면 null). `select(where).one()` 의 단축형입니다.
+     * 전역 훅이 적용됩니다.
      *
      * @example
      * ```ts
      * const user = await repo.selectOne({ id: 1 });
+     * const user = await repo.selectOne({ email: 'foo@bar.com' });
      * ```
      */
     async selectOne(where) {
         try {
-            return await new builder_1.QueryBuilder(this.tableName, where).one();
+            return await this.select(where).one();
         }
         catch (err) {
             throw dbError_1.DbError.from(err);

package/dist/features/schema/column.d.ts

@@ -13,25 +13,38 @@ export declare class Col<T = unknown, IsOpt extends boolean = false, IsPrimary e
     readonly hasDefault: boolean;
     readonly isPrimary: boolean;
     readonly length?: number | undefined;
+    /** DEFAULT NOW() 여부 — SQL 힌트 용도 */
+    readonly isDefaultNow: boolean;
     readonly _type: T;
     readonly _isOpt: IsOpt;
     readonly _isPrimary: IsPrimary;
-    constructor(pgType: string, isNullable?: boolean, hasDefault?: boolean, isPrimary?: boolean, length?: number | undefined);
+    constructor(pgType: string, isNullable?: boolean, hasDefault?: boolean, isPrimary?: boolean, length?: number | undefined, 
+    /** DEFAULT NOW() 여부 — SQL 힌트 용도 */
+    isDefaultNow?: boolean);
     /** 컬럼을 nullable로 설정합니다. (INSERT도 optional) */
     nullable(): Col<T | null, true, IsPrimary>;
-    /**
-     * 런타임에서 INSERT optional 여부를 반환합니다.
-     * isNullable, hasDefault, isPrimary 중 하나라도 true 이면 optional입니다.
-     */
-    get isOptional(): boolean;
     /** 컬럼을 NOT NULL로 설정합니다. */
     notNull(): Col<Exclude<T, null>, false, IsPrimary>;
     /** primary key로 설정합니다. (INSERT optional) */
     primaryKey(): Col<T, true, true>;
-    /** DB 기본값이 있는 컬럼으로 설정합니다. (INSERT optional) */
+    /**
+     * DB 기본값이 있는 컬럼으로 설정합니다. (INSERT optional)
+     *
+     * @example col.boolean().default()      // BOOLEAN DEFAULT false 등
+     */
     default(): Col<T, true, IsPrimary>;
-    /** DEFAULT NOW() 컬럼으로 설정합니다. (INSERT optional) */
+    /**
+     * DEFAULT NOW() 컬럼으로 설정합니다. (INSERT optional)
+     * `default()`와 타입은 동일하나 `isDefaultNow: true`로 구분됩니다.
+     *
+     * @example col.timestamptz().defaultNow()
+     */
     defaultNow(): Col<T, true, IsPrimary>;
+    /**
+     * 런타임에서 INSERT optional 여부를 반환합니다.
+     * isNullable, hasDefault, isPrimary 중 하나라도 true이면 optional입니다.
+     */
+    get isOptional(): boolean;
 }
 /**
  * 컬럼 빌더 팩토리.
@@ -39,9 +52,11 @@ export declare class Col<T = unknown, IsOpt extends boolean = false, IsPrimary e
  * @example
  * ```ts
  * const usersTable = defineTable('users', {
- *   id:    col.serial().primaryKey(),
- *   name:  col.varchar(255).notNull(),
- *   email: col.text().notNull(),
+ *   id:        col.serial().primaryKey(),
+ *   name:      col.varchar(255).notNull(),
+ *   email:     col.text().notNull(),
+ *   isActive:  col.boolean().default(),
+ *   createdAt: col.timestamptz().defaultNow(),
  * });
  * ```
  */

package/dist/features/schema/column.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"column.d.ts","sourceRoot":"","sources":["../../../src/features/schema/column.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;;;;;;GAOG;AACH,qBAAa,GAAG,CACd,CAAC,GAAG,OAAO,EACX,KAAK,SAAS,OAAO,GAAG,KAAK,EAC7B,SAAS,SAAS,OAAO,GAAG,KAAK,CACjC,YAAW,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC;IAMtC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,UAAU,EAAE,OAAO;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAT1B,SAAiB,KAAK,EAAE,CAAC,CAAC;IAC1B,SAAiB,MAAM,EAAE,KAAK,CAAC;IAC/B,SAAiB,UAAU,EAAE,SAAS,CAAC;gBAG5B,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,OAAe,EAC3B,UAAU,GAAE,OAAe,EAC3B,SAAS,GAAE,OAAe,EAC1B,MAAM,CAAC,EAAE,MAAM,YAAA;IAG1B,8CAA8C;IAC9C,QAAQ,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC;IAI1C;;;OAGG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,2BAA2B;IAC3B,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC;IAIlD,4CAA4C;IAC5C,UAAU,IAAI,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;IAIhC,+CAA+C;IAC/C,OAAO,IAAI,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;IAIlC,kDAAkD;IAClD,UAAU,IAAI,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;CAGtC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,GAAG;;;;;oBAKM,MAAM;;;;;;;YAOZ,CAAC;CAChB,CAAC"}
+{"version":3,"file":"column.d.ts","sourceRoot":"","sources":["../../../src/features/schema/column.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;;;;;;GAOG;AACH,qBAAa,GAAG,CACd,CAAC,GAAG,OAAO,EACX,KAAK,SAAS,OAAO,GAAG,KAAK,EAC7B,SAAS,SAAS,OAAO,GAAG,KAAK,CACjC,YAAW,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC;IAMtC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,UAAU,EAAE,OAAO;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IACxB,mCAAmC;IACnC,QAAQ,CAAC,YAAY,EAAE,OAAO;IAXhC,SAAiB,KAAK,EAAE,CAAC,CAAC;IAC1B,SAAiB,MAAM,EAAE,KAAK,CAAC;IAC/B,SAAiB,UAAU,EAAE,SAAS,CAAC;gBAG5B,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,OAAe,EAC3B,UAAU,GAAE,OAAe,EAC3B,SAAS,GAAE,OAAe,EAC1B,MAAM,CAAC,EAAE,MAAM,YAAA;IACxB,mCAAmC;IAC1B,YAAY,GAAE,OAAe;IAGxC,8CAA8C;IAC9C,QAAQ,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC;IAM1C,2BAA2B;IAC3B,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC;IAMlD,4CAA4C;IAC5C,UAAU,IAAI,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;IAMhC;;;;OAIG;IACH,OAAO,IAAI,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;IAMlC;;;;;OAKG;IACH,UAAU,IAAI,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;IAMrC;;;OAGG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,GAAG;;;;;oBAKM,MAAM;;;;;;;YAOZ,CAAC;CAChB,CAAC"}

package/dist/features/schema/column.js

@@ -10,39 +10,51 @@ exports.col = exports.Col = void 0;
  * - IsPrimary: primary key 여부
  */
 class Col {
-    constructor(pgType, isNullable = false, hasDefault = false, isPrimary = false, length) {
+    constructor(pgType, isNullable = false, hasDefault = false, isPrimary = false, length, 
+    /** DEFAULT NOW() 여부 — SQL 힌트 용도 */
+    isDefaultNow = false) {
         this.pgType = pgType;
         this.isNullable = isNullable;
         this.hasDefault = hasDefault;
         this.isPrimary = isPrimary;
         this.length = length;
+        this.isDefaultNow = isDefaultNow;
     }
     /** 컬럼을 nullable로 설정합니다. (INSERT도 optional) */
     nullable() {
-        return new Col(this.pgType, true, this.hasDefault, this.isPrimary, this.length);
-    }
-    /**
-     * 런타임에서 INSERT optional 여부를 반환합니다.
-     * isNullable, hasDefault, isPrimary 중 하나라도 true 이면 optional입니다.
-     */
-    get isOptional() {
-        return this.isNullable || this.hasDefault || this.isPrimary;
+        return new Col(this.pgType, true, this.hasDefault, this.isPrimary, this.length, this.isDefaultNow);
     }
     /** 컬럼을 NOT NULL로 설정합니다. */
     notNull() {
-        return new Col(this.pgType, false, this.hasDefault, this.isPrimary, this.length);
+        return new Col(this.pgType, false, this.hasDefault, this.isPrimary, this.length, this.isDefaultNow);
     }
     /** primary key로 설정합니다. (INSERT optional) */
     primaryKey() {
-        return new Col(this.pgType, this.isNullable, true, true, this.length);
+        return new Col(this.pgType, this.isNullable, true, true, this.length, this.isDefaultNow);
     }
-    /** DB 기본값이 있는 컬럼으로 설정합니다. (INSERT optional) */
+    /**
+     * DB 기본값이 있는 컬럼으로 설정합니다. (INSERT optional)
+     *
+     * @example col.boolean().default()      // BOOLEAN DEFAULT false 등
+     */
     default() {
-        return new Col(this.pgType, this.isNullable, true, this.isPrimary, this.length);
+        return new Col(this.pgType, this.isNullable, true, this.isPrimary, this.length, false);
     }
-    /** DEFAULT NOW() 컬럼으로 설정합니다. (INSERT optional) */
+    /**
+     * DEFAULT NOW() 컬럼으로 설정합니다. (INSERT optional)
+     * `default()`와 타입은 동일하나 `isDefaultNow: true`로 구분됩니다.
+     *
+     * @example col.timestamptz().defaultNow()
+     */
     defaultNow() {
-        return new Col(this.pgType, this.isNullable, true, this.isPrimary, this.length);
+        return new Col(this.pgType, this.isNullable, true, this.isPrimary, this.length, true);
+    }
+    /**
+     * 런타임에서 INSERT optional 여부를 반환합니다.
+     * isNullable, hasDefault, isPrimary 중 하나라도 true이면 optional입니다.
+     */
+    get isOptional() {
+        return this.isNullable || this.hasDefault || this.isPrimary;
     }
 }
 exports.Col = Col;
@@ -52,9 +64,11 @@ exports.Col = Col;
  * @example
  * ```ts
  * const usersTable = defineTable('users', {
- *   id:    col.serial().primaryKey(),
- *   name:  col.varchar(255).notNull(),
- *   email: col.text().notNull(),
+ *   id:        col.serial().primaryKey(),
+ *   name:      col.varchar(255).notNull(),
+ *   email:     col.text().notNull(),
+ *   isActive:  col.boolean().default(),
+ *   createdAt: col.timestamptz().defaultNow(),
  * });
  * ```
  */

package/dist/features/schema/interfaces/Infer.d.ts

@@ -13,7 +13,14 @@ export type InferInsert<TDef extends TableDef<string, Cols>> = {
 } & {
     [K in keyof TDef['cols'] as TDef['cols'][K]['_isOpt'] extends true ? K : never]?: TDef['cols'][K]['_type'];
 };
-/** UPDATE 입력 타입: primary key 제외, 모두 optional */
+/**
+ * UPDATE 입력 타입: primary key 제외, 모두 optional.
+ *
+ * 빈 객체(`{}`) 방지는 `buildUpdate`의 런타임 가드가 담당합니다.
+ *
+ * @example
+ * const update: InferUpdate<typeof usersTable> = { name: 'Alice' };
+ */
 export type InferUpdate<TDef extends TableDef<string, Cols>> = {
     [K in keyof TDef['cols'] as TDef['cols'][K]['_isPrimary'] extends true ? never : K]?: TDef['cols'][K]['_type'];
 };

package/dist/features/schema/interfaces/Infer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Infer.d.ts","sourceRoot":"","sources":["../../../../src/features/schema/interfaces/Infer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEzC,6BAA6B;AAC7B,MAAM,MAAM,QAAQ,CAAC,IAAI,SAAS,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI;KACzD,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CACpD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,IACzD;KAAG,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CAAE,GAC7G;KAAG,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CAAE,CAAC;AAEjH,gDAAgD;AAChD,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI;KAC5D,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CAC/G,CAAC"}
+{"version":3,"file":"Infer.d.ts","sourceRoot":"","sources":["../../../../src/features/schema/interfaces/Infer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEzC,6BAA6B;AAC7B,MAAM,MAAM,QAAQ,CAAC,IAAI,SAAS,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI;KACzD,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CACpD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,IACzD;KAAG,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CAAE,GAC7G;KAAG,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CAAE,CAAC;AAEjH;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI;KAC5D,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CAC/G,CAAC"}

package/dist/features/transform/case.d.ts

@@ -1,11 +1,21 @@
 /**
  * snake_case 문자열을 camelCase로 변환합니다.
- * 예: "first_name" → "firstName"
+ *
+ * @example
+ * toCamel('first_name')  // 'firstName'
+ * toCamel('user_id')     // 'userId'
+ * toCamel('url_param')   // 'urlParam'
  */
 export declare function toCamel(str: string): string;
 /**
  * camelCase 문자열을 snake_case로 변환합니다.
- * 예: "firstName" → "first_name"
+ * 두문자어(Acronym)도 올바르게 처리합니다.
+ *
+ * @example
+ * toSnake('firstName')  // 'first_name'
+ * toSnake('userId')     // 'user_id'
+ * toSnake('URLParam')   // 'url_param'
+ * toSnake('userID')     // 'user_id'
  */
 export declare function toSnake(str: string): string;
 /**

package/dist/features/transform/case.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"case.d.ts","sourceRoot":"","sources":["../../../src/features/transform/case.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIjF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIjF"}
+{"version":3,"file":"case.d.ts","sourceRoot":"","sources":["../../../src/features/transform/case.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO3C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIjF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIjF"}

package/dist/features/transform/case.js

@@ -6,17 +6,32 @@ exports.keysToCamel = keysToCamel;
 exports.keysToSnake = keysToSnake;
 /**
  * snake_case 문자열을 camelCase로 변환합니다.
- * 예: "first_name" → "firstName"
+ *
+ * @example
+ * toCamel('first_name')  // 'firstName'
+ * toCamel('user_id')     // 'userId'
+ * toCamel('url_param')   // 'urlParam'
  */
 function toCamel(str) {
-    return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    return str.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
 }
 /**
  * camelCase 문자열을 snake_case로 변환합니다.
- * 예: "firstName" → "first_name"
+ * 두문자어(Acronym)도 올바르게 처리합니다.
+ *
+ * @example
+ * toSnake('firstName')  // 'first_name'
+ * toSnake('userId')     // 'user_id'
+ * toSnake('URLParam')   // 'url_param'
+ * toSnake('userID')     // 'user_id'
  */
 function toSnake(str) {
-    return str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+    return str
+        // 연속 대문자 뒤에 소문자가 오는 경우: "URLParam" → "URL_Param"
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        // 소문자/숫자 뒤에 대문자: "camelCase" → "camel_Case"
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase();
 }
 /**
  * 객체의 모든 key를 camelCase로 변환합니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reltype",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Type-first relational modeling for PostgreSQL in TypeScript. Fluent query builder with automatic camelCase ↔ snake_case conversion, CRUD, streaming, cursor pagination, and hooks.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,12 +59,10 @@
   "peerDependencies": {
     "pg": ">=8.0.0"
   },
-  "dependencies": {
-    "dotenv": "^17.3.1"
-  },
   "devDependencies": {
     "@types/express": "^4.17.25",
     "@types/pg": "^8.16.0",
+    "dotenv": "^17.3.1",
     "express": "^5.2.1",
     "nodemon": "^3.1.11",
     "pg": "^8.18.0",