reltype 0.1.1

package/dist/configs/env.d.ts

@@ -0,0 +1,14 @@
+import { DatabaseConfig } from '../interfaces/DatabaseConfig';
+/**
+ * 환경 변수에서 DatabaseConfig를 파싱합니다.
+ * Pool 관리는 features/connection/pool.ts 를 사용하세요.
+ *
+ * @note 라이브러리는 process.env를 읽기만 합니다.
+ *       dotenv.config() 호출은 애플리케이션 진입점에서 직접 하세요:
+ *       ```ts
+ *       import 'dotenv/config';             // ESM
+ *       require('dotenv').config();          // CJS
+ *       ```
+ */
+export declare function getDatabaseConfig(): DatabaseConfig;
+//# sourceMappingURL=env.d.ts.map

package/dist/configs/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/configs/env.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAqClD"}

package/dist/configs/env.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDatabaseConfig = getDatabaseConfig;
+const reader_1 = require("../utils/reader");
+/**
+ * 환경 변수에서 DatabaseConfig를 파싱합니다.
+ * Pool 관리는 features/connection/pool.ts 를 사용하세요.
+ *
+ * @note 라이브러리는 process.env를 읽기만 합니다.
+ *       dotenv.config() 호출은 애플리케이션 진입점에서 직접 하세요:
+ *       ```ts
+ *       import 'dotenv/config';             // ESM
+ *       require('dotenv').config();          // CJS
+ *       ```
+ */
+function getDatabaseConfig() {
+    const env = process.env;
+    const connectionString = env.DB_CONNECTION_STRING;
+    const config = {
+        host: (0, reader_1.readEnv)(env, 'DB_HOST', '127.0.0.1'),
+        port: (0, reader_1.readEnv)(env, 'DB_PORT', 5432),
+        database: env.DB_NAME,
+        user: (0, reader_1.readEnv)(env, 'DB_USER', 'postgres'),
+        password: (0, reader_1.readEnv)(env, 'DB_PASSWORD', 'postgres'),
+        connectionString,
+        ssl: env.DB_SSL !== undefined
+            ? (0, reader_1.readEnv)(env, 'DB_SSL', false)
+            : undefined,
+        max: env.DB_MAX ? (0, reader_1.readEnv)(env, 'DB_MAX', 10) : undefined,
+        idleTimeoutMillis: env.DB_IDLE_TIMEOUT ? (0, reader_1.readEnv)(env, 'DB_IDLE_TIMEOUT', 30000) : undefined,
+        connectionTimeoutMillis: env.DB_CONNECTION_TIMEOUT ? (0, reader_1.readEnv)(env, 'DB_CONNECTION_TIMEOUT', 2000) : undefined,
+        allowExitOnIdle: (0, reader_1.readEnv)(env, 'DB_ALLOW_EXIT_ON_IDLE', false) || undefined,
+        statement_timeout: env.DB_STATEMENT_TIMEOUT ? (0, reader_1.readEnv)(env, 'DB_STATEMENT_TIMEOUT', 0) : undefined,
+        query_timeout: env.DB_QUERY_TIMEOUT ? (0, reader_1.readEnv)(env, 'DB_QUERY_TIMEOUT', 0) : undefined,
+        application_name: env.DB_APPLICATION_NAME,
+        parseInputDatesAsUTC: (0, reader_1.readEnv)(env, 'DB_PARSE_INPUT_DATES_AS_UTC', false) || undefined,
+        keepAlive: (0, reader_1.readEnv)(env, 'DB_KEEP_ALIVE', true) || undefined,
+        keepAliveInitialDelayMillis: env.DB_KEEP_ALIVE_INITIAL_DELAY
+            ? (0, reader_1.readEnv)(env, 'DB_KEEP_ALIVE_INITIAL_DELAY', 10000)
+            : undefined,
+    };
+    if (!config.connectionString && !config.database) {
+        throw new Error('DB config error: DB_CONNECTION_STRING 또는 DB_NAME 중 하나는 필수입니다.');
+    }
+    return config;
+}

package/dist/configs/index.d.ts

@@ -0,0 +1,2 @@
+export * from './env';
+//# sourceMappingURL=index.d.ts.map

package/dist/configs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/configs/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

package/dist/configs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./env"), exports);

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

@@ -0,0 +1,3 @@
+export * from './pool';
+export * from './tx';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/connection/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC"}

package/dist/features/connection/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./pool"), exports);
+__exportStar(require("./tx"), exports);

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

@@ -0,0 +1,42 @@
+import { Pool, PoolClient, PoolConfig } from 'pg';
+/** Pool 상태 스냅샷 */
+export interface PoolStatus {
+    /** 총 생성된 연결 수 */
+    totalCount: number;
+    /** 현재 유휴 연결 수 */
+    idleCount: number;
+    /** 연결 대기 중인 요청 수 */
+    waitingCount: number;
+    /** Pool이 정상 상태인지 여부 */
+    isHealthy: boolean;
+}
+/**
+ * 싱글턴 Pool을 반환합니다.
+ *
+ * - 최초 호출 시 환경 변수 또는 config로 Pool을 생성합니다.
+ * - connectionTimeoutMillis 미설정 시 경고를 출력합니다.
+ * - Pool 에러 이벤트를 감지해 로깅합니다.
+ */
+export declare function getPool(config?: PoolConfig): Pool;
+/**
+ * Pool에서 client를 빌려 콜백을 실행한 뒤 자동으로 release합니다.
+ *
+ * - 연결 획득 실패(연결 수 초과, 타임아웃 등)는 DbError로 변환됩니다.
+ * - client는 성공/실패 여부와 무관하게 반드시 release됩니다.
+ */
+export declare function withClient<T>(fn: (client: PoolClient) => Promise<T>): Promise<T>;
+/**
+ * 현재 Pool 상태를 반환합니다.
+ * Pool이 생성되지 않았을 경우 모든 값이 0입니다.
+ */
+export declare function getPoolStatus(): PoolStatus;
+/**
+ * Pool과 DB 서버 간의 연결이 살아있는지 확인합니다.
+ * `SELECT 1` 쿼리를 실행하고 결과를 반환합니다.
+ */
+export declare function checkPoolHealth(): Promise<boolean>;
+/**
+ * 애플리케이션 종료 시 Pool을 안전하게 닫습니다.
+ */
+export declare function closePool(): Promise<void>;
+//# sourceMappingURL=pool.d.ts.map

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

@@ -0,0 +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"}

package/dist/features/connection/pool.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPool = getPool;
+exports.withClient = withClient;
+exports.getPoolStatus = getPoolStatus;
+exports.checkPoolHealth = checkPoolHealth;
+exports.closePool = closePool;
+const pg_1 = require("pg");
+const logger_1 = require("../../utils/logger");
+const dbError_1 = require("../../utils/dbError");
+const reader_1 = require("../../utils/reader");
+const logger = logger_1.Logger.fromEnv(process.env, { prefix: '[Pool]', level: 'info' });
+let _pool = null;
+/** 설정된 최대 연결 수 (경고 임계값 계산용) */
+let _maxConnections = 10;
+/**
+ * 싱글턴 Pool을 반환합니다.
+ *
+ * - 최초 호출 시 환경 변수 또는 config로 Pool을 생성합니다.
+ * - connectionTimeoutMillis 미설정 시 경고를 출력합니다.
+ * - Pool 에러 이벤트를 감지해 로깅합니다.
+ */
+function getPool(config) {
+    if (_pool)
+        return _pool;
+    const cfg = config ??
+        reader_1.PostgresConfig.fromEnv(new reader_1.NodeEnvSource(process.env)).toDriverOptions();
+    _maxConnections = cfg.max ?? 10;
+    if (!cfg.connectionTimeoutMillis) {
+        logger.warn('connectionTimeoutMillis 미설정: 연결 획득 시 무한 대기가 발생할 수 있습니다. ' +
+            'DB_CONNECTION_TIMEOUT 환경 변수를 설정하세요.');
+    }
+    _pool = new pg_1.Pool(cfg);
+    _pool.on('error', (err, client) => {
+        const dbErr = dbError_1.DbError.from(err);
+        logger.error('유휴 클라이언트 오류', {
+            ...dbErr.toLogContext(),
+            clientPid: client.processID,
+        });
+    });
+    _pool.on('connect', () => {
+        const status = readPoolStatus(_pool);
+        logger.debug('새 연결 생성', {
+            totalCount: status.totalCount,
+            idleCount: status.idleCount,
+            waitingCount: status.waitingCount,
+        });
+        if (status.totalCount >= _maxConnections) {
+            logger.warn('Pool이 최대 연결 수에 도달했습니다.', {
+                totalCount: status.totalCount,
+                max: _maxConnections,
+            });
+        }
+    });
+    _pool.on('remove', () => {
+        logger.debug('연결 제거됨', { totalCount: _pool?.totalCount ?? 0 });
+    });
+    logger.info('Pool 생성 완료', {
+        max: _maxConnections,
+        connectionTimeoutMillis: cfg.connectionTimeoutMillis,
+        idleTimeoutMillis: cfg.idleTimeoutMillis,
+    });
+    return _pool;
+}
+/**
+ * Pool에서 client를 빌려 콜백을 실행한 뒤 자동으로 release합니다.
+ *
+ * - 연결 획득 실패(연결 수 초과, 타임아웃 등)는 DbError로 변환됩니다.
+ * - client는 성공/실패 여부와 무관하게 반드시 release됩니다.
+ */
+async function withClient(fn) {
+    let client;
+    try {
+        client = await getPool().connect();
+    }
+    catch (err) {
+        const dbErr = dbError_1.DbError.from(err);
+        logger.error('클라이언트 획득 실패', dbErr.toLogContext());
+        throw dbErr;
+    }
+    try {
+        return await fn(client);
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * 현재 Pool 상태를 반환합니다.
+ * Pool이 생성되지 않았을 경우 모든 값이 0입니다.
+ */
+function getPoolStatus() {
+    if (!_pool) {
+        return { totalCount: 0, idleCount: 0, waitingCount: 0, isHealthy: true };
+    }
+    return readPoolStatus(_pool);
+}
+/**
+ * Pool과 DB 서버 간의 연결이 살아있는지 확인합니다.
+ * `SELECT 1` 쿼리를 실행하고 결과를 반환합니다.
+ */
+async function checkPoolHealth() {
+    try {
+        await withClient(async (client) => {
+            await client.query('SELECT 1');
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 애플리케이션 종료 시 Pool을 안전하게 닫습니다.
+ */
+async function closePool() {
+    if (!_pool)
+        return;
+    const p = _pool;
+    _pool = null;
+    await p.end();
+    logger.info('Pool 종료 완료');
+}
+function readPoolStatus(pool) {
+    return {
+        totalCount: pool.totalCount,
+        idleCount: pool.idleCount,
+        waitingCount: pool.waitingCount,
+        isHealthy: pool.idleCount > 0 || pool.waitingCount === 0,
+    };
+}

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

@@ -0,0 +1,10 @@
+import { PoolClient } from 'pg';
+/**
+ * 트랜잭션 내에서 콜백을 실행합니다.
+ *
+ * - 성공 시 COMMIT, 실패 시 ROLLBACK됩니다.
+ * - ROLLBACK 실패 시에도 원래 에러가 전파됩니다.
+ * - 모든 에러는 DbError로 변환됩니다.
+ */
+export declare function runInTx<T>(fn: (client: PoolClient) => Promise<T>): Promise<T>;
+//# sourceMappingURL=tx.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tx.d.ts","sourceRoot":"","sources":["../../../src/features/connection/tx.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAUhC;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC,CAuBZ"}

package/dist/features/connection/tx.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInTx = runInTx;
+const logger_1 = require("../../utils/logger");
+const dbError_1 = require("../../utils/dbError");
+const pool_1 = require("./pool");
+const logger = logger_1.Logger.fromEnv(process.env, { prefix: '[Tx]' });
+/**
+ * 트랜잭션 내에서 콜백을 실행합니다.
+ *
+ * - 성공 시 COMMIT, 실패 시 ROLLBACK됩니다.
+ * - ROLLBACK 실패 시에도 원래 에러가 전파됩니다.
+ * - 모든 에러는 DbError로 변환됩니다.
+ */
+async function runInTx(fn) {
+    return (0, pool_1.withClient)(async (client) => {
+        await client.query('BEGIN');
+        logger.debug('트랜잭션 시작');
+        try {
+            const result = await fn(client);
+            await client.query('COMMIT');
+            logger.debug('트랜잭션 커밋');
+            return result;
+        }
+        catch (err) {
+            const dbErr = dbError_1.DbError.from(err);
+            try {
+                await client.query('ROLLBACK');
+                logger.warn('트랜잭션 롤백', dbErr.toLogContext());
+            }
+            catch (rollbackErr) {
+                logger.error('롤백 실패', dbError_1.DbError.from(rollbackErr).toLogContext());
+            }
+            throw dbErr;
+        }
+    });
+}

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

@@ -0,0 +1,253 @@
+import { AdvancedWhere, JoinClause, AggregateCalc, PaginateOpts, PageResult, OrderByClause, KeysetPaginateOpts, KeysetPageResult, StreamOpts, ExecHooks } from './interfaces/Advanced';
+/**
+ * 플루언트 쿼리 빌더.
+ *
+ * ### 기본 사용
+ * ```ts
+ * const users = await repo.select({ isActive: true })
+ *   .or({ email: { operator: 'ILIKE', value: '%@gmail.com' } })
+ *   .orderBy([{ column: 'createdAt', direction: 'DESC' }])
+ *   .limit(20);
+ * ```
+ *
+ * ### 페이지네이션 (OFFSET 방식)
+ * ```ts
+ * const page = await repo.select().paginate({ page: 1, pageSize: 20 });
+ * ```
+ *
+ * ### 커서 기반 페이지네이션 (대용량 최적화)
+ * ```ts
+ * const p1 = await repo.select().cursorPaginate({ pageSize: 20, cursorColumn: 'id' });
+ * const p2 = await repo.select().cursorPaginate({ pageSize: 20, cursorColumn: 'id', cursor: p1.nextCursor });
+ * ```
+ *
+ * ### 스트리밍 (메모리 효율)
+ * ```ts
+ * for await (const user of repo.select().stream()) {
+ *   await processRow(user);
+ * }
+ * ```
+ *
+ * ### 배치 처리
+ * ```ts
+ * await repo.select().forEach(async (batch) => {
+ *   await processBatch(batch);
+ * }, { batchSize: 500 });
+ * ```
+ *
+ * ### 훅
+ * ```ts
+ * repo.select()
+ *   .hooks({ beforeExec: ({ sql }) => console.log(sql) })
+ *   .exec();
+ * ```
+ */
+export declare class QueryBuilder<T extends Record<string, unknown>> {
+    private readonly _table;
+    private _andConds;
+    private _orConds;
+    private _orderByClauses;
+    private _limitVal?;
+    private _offsetVal?;
+    private _groupByCols;
+    private _joins;
+    private _cols;
+    private _execHooks?;
+    constructor(table: string, initWhere?: AdvancedWhere<T>);
+    /** AND 조건 추가 */
+    where(conditions: AdvancedWhere<T>): this;
+    /** OR 조건 추가 */
+    or(conditions: AdvancedWhere<T>): this;
+    /**
+     * ORDER BY 설정
+     * @example .orderBy([{ column: 'createdAt', direction: 'DESC' }])
+     */
+    orderBy(clauses: OrderByClause<T>[]): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    /**
+     * GROUP BY 설정
+     * @example .groupBy(['status', 'isActive'])
+     */
+    groupBy(columns: Array<keyof T | string>): this;
+    /**
+     * JOIN 추가 (여러 번 호출 가능)
+     * @example
+     * .join({ table: 'orders', on: 'users.id = orders.user_id', type: 'LEFT' })
+     */
+    join(j: JoinClause): this;
+    /**
+     * SELECT 할 컬럼 지정 (기본값: *)
+     * @example .columns(['id', 'email', 'firstName'])
+     */
+    columns(cols: Array<keyof T | string>): this;
+    /**
+     * 쿼리 실행 라이프사이클 훅을 등록합니다.
+     *
+     * @example
+     * ```ts
+     * repo.select()
+     *   .hooks({
+     *     beforeExec: ({ sql }) => logger.debug('SQL:', sql),
+     *     afterExec:  ({ elapsed }) => metrics.record(elapsed),
+     *     onError:    ({ err }) => alerting.notify(err),
+     *   })
+     *   .exec();
+     * ```
+     */
+    hooks(h: ExecHooks<T>): this;
+    /**
+     * 쿼리를 실행하고 rows 배열을 반환합니다.
+     * `await builder` 와 동일합니다.
+     */
+    exec(): Promise<T[]>;
+    /**
+     * 첫 번째 row 하나를 반환합니다. 없으면 null입니다.
+     */
+    one(): Promise<T | null>;
+    /**
+     * 집계 함수를 실행합니다.
+     *
+     * @example
+     * ```ts
+     * const result = await repo.select({ isActive: true })
+     *   .calculate([
+     *     { fn: 'COUNT', alias: 'count' },
+     *     { fn: 'AVG', column: 'price', alias: 'avgPrice' },
+     *   ]);
+     * // → { count: '5', avgPrice: '12000.00' }
+     * ```
+     */
+    calculate(fns: AggregateCalc[]): Promise<Record<string, unknown>>;
+    /**
+     * OFFSET 기반 페이지네이션.
+     * COUNT + DATA 쿼리를 병렬로 실행합니다.
+     *
+     * > 수백만 건 이상의 테이블에서는 `cursorPaginate()`를 사용하세요.
+     *
+     * @example
+     * ```ts
+     * const result = await repo.select()
+     *   .paginate({ page: 1, pageSize: 20 });
+     * // → { data, count, page, pageSize, nextAction, previousAction }
+     * ```
+     */
+    paginate(opts: PaginateOpts): Promise<PageResult<T>>;
+    /**
+     * 커서(Keyset) 기반 페이지네이션.
+     *
+     * OFFSET 스캔 없이 `WHERE cursor_col > last_value` 방식으로 동작하므로
+     * 수천만 건 규모에서도 일정한 응답 속도를 보장합니다.
+     *
+     * - `cursorColumn`에는 반드시 인덱스가 존재해야 합니다.
+     * - 결과는 항상 `cursorColumn` 기준으로 정렬됩니다.
+     *
+     * @example
+     * ```ts
+     * // 첫 페이지
+     * const p1 = await repo.select({ isActive: true })
+     *   .cursorPaginate({ pageSize: 20, cursorColumn: 'id' });
+     *
+     * // 다음 페이지
+     * if (p1.hasNext) {
+     *   const p2 = await repo.select({ isActive: true })
+     *     .cursorPaginate({ pageSize: 20, cursorColumn: 'id', cursor: p1.nextCursor });
+     * }
+     * ```
+     */
+    cursorPaginate(opts: KeysetPaginateOpts): Promise<KeysetPageResult<T>>;
+    /**
+     * 결과를 배치 단위로 처리합니다. 전체 데이터를 메모리에 올리지 않습니다.
+     *
+     * 대용량 테이블의 일괄 처리(ETL, 이메일 발송, 마이그레이션 등)에 적합합니다.
+     *
+     * @param fn        - 배치 배열을 받아 처리하는 비동기 함수
+     * @param opts.batchSize - 한 번에 처리할 row 수 (기본값: 500)
+     *
+     * @example
+     * ```ts
+     * await repo.select({ isActive: true })
+     *   .orderBy([{ column: 'id', direction: 'ASC' }])
+     *   .forEach(async (batch) => {
+     *     await sendEmailBatch(batch);
+     *   }, { batchSize: 200 });
+     * ```
+     */
+    forEach(fn: (batch: T[]) => Promise<void>, opts?: StreamOpts): Promise<void>;
+    /**
+     * AsyncGenerator로 row를 하나씩 yield합니다.
+     * 내부적으로 배치 단위로 DB를 조회하여 메모리 효율을 유지합니다.
+     *
+     * @param opts.batchSize - 내부 배치 크기 (기본값: 500)
+     *
+     * @example
+     * ```ts
+     * for await (const user of repo.select({ isActive: true }).stream()) {
+     *   await processRow(user);
+     * }
+     * ```
+     */
+    stream(opts?: StreamOpts): AsyncGenerator<T, void, unknown>;
+    /**
+     * `for await...of` 직접 사용을 지원합니다. `.stream()` 과 동일합니다.
+     *
+     * @example
+     * ```ts
+     * for await (const user of repo.select()) {
+     *   // 각 row를 순서대로 처리
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<T, void, unknown>;
+    /**
+     * EXPLAIN (ANALYZE) 결과를 반환합니다.
+     * 쿼리 플랜 분석 및 인덱스 사용 여부 확인에 사용합니다.
+     *
+     * @param analyze - true이면 실제 실행 후 통계를 포함합니다 (기본값: false)
+     *
+     * @example
+     * ```ts
+     * const plan = await repo.select({ isActive: true }).explain(true);
+     * console.log(plan);
+     * ```
+     */
+    explain(analyze?: boolean): Promise<string>;
+    /**
+     * 현재 builder 상태에서 최종 SQL과 params를 반환합니다.
+     * 디버깅 또는 로깅 목적으로 사용합니다.
+     */
+    toSQL(): {
+        sql: string;
+        params: unknown[];
+    };
+    /**
+     * Raw SQL을 직접 실행합니다.
+     * DB 컬럼명(snake_case) → TypeScript(camelCase) 자동 변환이 적용됩니다.
+     *
+     * @example
+     * ```ts
+     * const rows = await QueryBuilder.raw<UserRow>(
+     *   'SELECT * FROM users WHERE first_name ILIKE $1',
+     *   ['%john%'],
+     * );
+     * ```
+     */
+    static raw<R extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<R[]>;
+    /**
+     * builder 상태를 독립적으로 복사합니다.
+     * 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>;
+    catch<R = never>(onrejected: ((reason: unknown) => R | PromiseLike<R>) | null | undefined): Promise<T[] | R>;
+    private buildWhereParts;
+    private buildJoinSQL;
+    private buildGroupBySQL;
+    private buildOrderBySQL;
+    private buildSelectSQL;
+    /**
+     * 공통 쿼리 실행 (훅 + 로깅 포함).
+     */
+    private runQuery;
+}
+//# sourceMappingURL=builder.d.ts.map

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

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