supalite 0.1.13 → 0.2.1

package/CHANGELOG.md

@@ -1,52 +1,15 @@
 # Changelog
 
-## [0.1.13] - 2025-03-02
+## [0.1.8] - 2025-03-04
 
 ### Fixed
-- modified_at과 updated_at 필드를 nullable로 변경하여 NULL 값 처리 개선
-- 타입 안전성 향상
+- 누락된 `dist` 파일들을 포함하도록 수정
 
-## [0.1.12] - 2025-03-02
+## [0.1.7] - 2025-03-04
 
 ### Added
-- Views 테이블 조회 기능 추가
-- TableOrViewName 타입 추가로 Tables와 Views 모두 지원
-- View 테이블 조회 예제 코드 추가
-- View 테이블 테스트를 위한 SQL 스크립트 추가
-
-## [0.1.11] - 2025-03-02
-
-### Fixed
-- 빌드 결과물 업데이트 및 배포 문제 해결
-
-## [0.1.10] - 2025-03-02
-
-### Fixed
-- order 메서드를 수정하여 컬럼 이름만 전달하는 경우에도 기본적으로 오름차순 정렬이 적용되도록 개선
-- Supabase와의 호환성 개선 (.order('post_index') 형식 지원)
-- order 메서드 사용 예제 추가
-
-## [0.1.9] - 2025-03-02
-
-### Fixed
-- from 메서드의 반환 타입을 수정하여 single() 메서드를 호출할 때 SingleQueryResult를 반환하도록 개선
-- 타입 단언 없이도 single() 메서드를 사용할 수 있도록 수정
-- single() 메서드 사용 예제 추가
-
-## [0.1.8] - 2025-03-02
-
-### Fixed
-- from 메서드의 반환 타입을 수정하여 타입 단언 없이도 배열 메서드를 사용할 수 있도록 개선
-- await 사용 시 자동으로 QueryResult<Row<T, S, K>>를 반환하도록 수정
-- Supabase와의 호환성 개선
-
-## [0.1.7] - 2025-03-02
-
-### Fixed
-- QueryResult 타입의 data 필드가 항상 배열을 반환하도록 수정
-- 쿼리 결과가 없을 때 null 대신 빈 배열([])을 반환하도록 수정
-- 에러 발생 시에도 data 필드가 빈 배열을 반환하도록 수정
-- Supabase와의 호환성 개선
+- QueryBuilder에 `match` 메서드 추가
+- `match` 메서드 테스트 코드 작성
 
 ## [0.1.6] - 2025-03-01
 

package/CHANGE_REPORT_LOG.md

@@ -1,65 +1,123 @@
-# 변경 사항 보고서 (2025-03-02)
+# 변경 작업 보고서
+
+## [2025-03-04] 누락된 dist 파일들을 포함하도록 수정
+
+### 작업 내용
+- 빌드 시 생성되는 dist 디렉토리의 파일들이 이전 커밋에 포함되지 않은 문제를 발견했습니다.
+- dist 디렉토리를 삭제하고 다시 빌드하여 누락된 파일들을 생성했습니다.
+- package.json 파일의 버전을 0.1.8로 업데이트했습니다.
+- CHANGELOG.md 파일에 변경 사항을 기록했습니다.
+
+### 변경된 파일
+- dist/*
+- package.json
+- CHANGELOG.md
+
+### 개발 과정
+1. dist 디렉토리 삭제
+2. npm run build 명령어 실행
+3. git add . 명령어로 변경된 파일 스테이징
+4. git commit -m "fix: Include missing files in dist directory" 명령어로 커밋
+5. package.json 파일의 버전 업데이트
+6. CHANGELOG.md 파일에 변경 사항 기록
+
+### 결론
+이번 작업을 통해 누락되었던 dist 파일들을 커밋에 포함시켰습니다.
+
+---
+
+## [2025-03-04] QueryBuilder에 match 메서드 추가
+
+### 작업 내용
+
+1.  **`match` 메서드 구현**:
+    - `QueryBuilder` 클래스에 `match` 메서드를 추가했습니다.
+    - 이 메서드는 객체를 인자로 받아, 객체의 각 키-값 쌍을 `"${key}" = $${index}` 형태의 조건으로 변환하여 `whereConditions` 배열에 추가합니다.
+    - 이를 통해 사용자는 객체 리터럴을 사용하여 간편하게 쿼리 조건을 추가할 수 있습니다.
+
+2.  **테스트용 테이블 생성**:
+    - `examples/setup.sql` 파일에 `test_table`을 생성하는 SQL 문을 추가했습니다.
+    - 이 테이블은 `match` 메서드의 동작을 테스트하는 데 사용됩니다.
+
+3.  **테스트용 함수 구현**:
+    - `src/test-table.ts` 파일에 `test_table`과 상호작용하는 함수를 작성했습니다.
+    - `insertIntoTestTable` 함수는 `test_table`에 데이터를 삽입합니다.
+    - `getFromTestTable` 함수는 `test_table`에서 데이터를 조회하고, `match` 메서드를 사용하여 조건을 적용합니다.
+
+4.  **테스트 코드 작성**:
+    - `examples/tests/query-builder.test.ts` 파일에 `match` 메서드를 테스트하는 코드를 작성했습니다.
+    - 이 코드는 `test_table`에 데이터를 삽입하고, `match` 메서드를 사용하여 다양한 조건으로 데이터를 조회합니다.
+    - 조회 결과가 예상과 일치하는지 확인합니다.
+
+5.  **테스트 실행**:
+    - `bun examples/tests/query-builder.test.ts` 명령어를 사용하여 테스트를 실행했습니다.
+    - 모든 테스트가 성공적으로 완료되었습니다.
+
+6.  **문서화**:
+     - CHANGELOG.md 파일에 `match` 메서드 추가 사항을 기록했습니다.
+     - 버전을 0.1.7로 업데이트했습니다.
+
+### 변경된 파일
+
+1.  `src/query-builder.ts`: `match` 메서드 추가
+2.  `examples/setup.sql`: `test_table` 생성 SQL 문 추가
+3.  `src/test-table.ts`: `test_table` 관련 함수 구현
+4.  `examples/tests/query-builder.test.ts`: `match` 메서드 테스트 코드 작성
+5.  `CHANGELOG.md`: 변경 사항 문서화 및 버전 업데이트
+
+### 개발 과정
+
+1.  `feature/add-match-method` 브랜치 생성
+2.  `QueryBuilder` 클래스에 `match` 메서드 구현
+3.  `examples/setup.sql` 파일에 `test_table` 생성 SQL 문 추가
+4.  `src/test-table.ts` 파일에 `test_table` 관련 함수 구현
+5.  `examples/tests/query-builder.test.ts` 파일에 `match` 메서드 테스트 코드 작성
+6.  테스트 실행 및 결과 확인
+7.  문서화 및 버전 업데이트
+8.  변경 사항 커밋
+9.  main 브랜치로 병합
+
+### 테스트 결과
+
+테스트 결과는 다음과 같습니다:
+
+```
+Result 1: [
+  {
+    id: 1
+    name: "test1"
+    value: 10
+  }
+]
+Result 2: [
+  {
+    id: 2
+    name: "test2"
+    value: 20
+  }
+]
+Result 3: [
+  {
+    id: 1
+    name: "test1"
+    value: 10
+  }
+]
+Result 4: null
+```
+
+Result1, 2, 3은 예상대로 출력되었고, Result 4는 존재하지 않는 데이터에 대한 결과로 null을 반환했습니다.
+
+### 결론
+
+이번 작업을 통해 `QueryBuilder` 클래스에 `match` 메서드를 추가하여, 사용자가 객체 리터럴을 사용하여 간편하게 쿼리 조건을 추가할 수 있게 되었습니다. 또한, 테스트 코드를 통해 `match` 메서드의 동작을 검증했습니다.
+
+---
+
+# 변경 작업 보고서
+
+## [2025-03-01] corepack을 통한 다중 패키지 관리자 지원 추가
+
+### 작업 내용
 
-## 버전 0.1.12 배포 완료
-
-### 1. 코드 변경 사항
-
-#### 타입 정의 수정 (`src/types.ts`)
-- `ViewName` 타입 추가: 스키마 내의 Views 이름을 참조하는 타입
-- `TableOrViewName` 타입 추가: Tables와 Views를 모두 포함하는 통합 타입
-- `Row`, `InsertRow`, `UpdateRow` 타입 수정: Views도 처리할 수 있도록 조건부 타입 적용
-
-#### 쿼리 빌더 수정 (`src/query-builder.ts`)
-- `QueryBuilder` 클래스의 제네릭 타입 매개변수를 `TableOrViewName`으로 변경
-
-#### PostgreSQL 클라이언트 수정 (`src/postgres-client.ts`)
-- `SchemaWithTables` 타입 수정: Views 타입 정의 추가
-- `from` 메서드 시그니처 수정: `TableOrViewName` 타입을 사용하도록 변경
-
-### 2. 예제 및 테스트 코드 추가
-
-#### 예제 데이터베이스 타입 정의 수정 (`examples/types/database.ts`)
-- 예제 데이터베이스 타입 정의에 Views 추가
-- `user_posts_view`와 `active_users_view` 뷰 정의 추가
-
-#### 테스트 및 예제 코드 추가
-- View 테이블 조회 예제 코드 작성 (`examples/tests/view-table.ts`)
-- 테스트용 SQL 스크립트 작성 (`examples/setup-views.sql`)
-- 모의 데이터를 사용한 테스트 코드 작성 (`examples/tests/mock-view-table.ts`)
-- 타입 안전성 테스트 코드 작성 (`examples/tests/view-table-test.ts`)
-- PostgreSQL 테스트 환경 설정 스크립트 작성 (`setup-postgres-test.sql`)
-
-### 3. 테스트 결과
-
-#### 타입 검증
-- TypeScript 컴파일러를 통한 타입 검증 완료
-- View 테이블 타입이 올바르게 추론됨
-- 타입 안전성 유지 (존재하지 않는 컬럼/테이블 접근 시 컴파일 오류 발생)
-- Views는 읽기 전용이므로 Insert/Update 시도 시 컴파일 오류 발생
-
-#### 모의 데이터 테스트
-- 모의 데이터를 사용한 View 테이블 조회 예제 실행 성공
-- 일반 테이블과 동일한 방식으로 View 테이블 조회 가능
-- 조건 적용, 정렬, 단일 결과 조회 등 다양한 쿼리 기능 정상 작동
-
-#### 실제 PostgreSQL 데이터베이스 테스트
-- PostgreSQL 테스트 환경 설정 및 테스트 데이터 생성 성공
-- 실제 데이터베이스에서 View 테이블 조회 기능 정상 작동 확인
-- 연결 문자열을 사용하여 인증 문제 해결
-
-### 4. 배포 과정
-
-#### 브랜치 관리
-- 브랜치 `feature/view-table-support` 생성
-- 변경 사항 커밋: "feat: Views 테이블 조회 기능 추가"
-- 테스트 코드 커밋: "test: View 테이블 조회 기능 테스트 코드 추가"
-- PostgreSQL 테스트 환경 설정 스크립트 커밋: "test: PostgreSQL 테스트 환경 설정 스크립트 추가"
-
-#### 머지 및 배포
-- `feature/view-table-support` 브랜치를 `main` 브랜치에 머지
-- 버전 0.1.12로 업데이트
-- npm에 배포 완료
-
-### 5. 결론
-
-이제 Supalite 라이브러리는 Supabase 데이터베이스의 Views 테이블도 조회할 수 있게 되었습니다. 사용자는 일반 테이블과 동일한 방식으로 View 테이블을 조회할 수 있으며, 타입 안전성과 기존 코드와의 호환성이 유지됩니다. 실제 PostgreSQL 데이터베이스에서도 정상적으로 작동함을 확인했습니다.
+... (생략) ...

package/README.md

@@ -1,6 +1,6 @@
 # SupaLite
 
-[![npm version](https://img.shields.io/badge/version-0.1.1-blue.svg)](https://www.npmjs.com/package/supalite)
+[![npm version](https://img.shields.io/badge/version-0.2.1-blue.svg)](https://www.npmjs.com/package/supalite)
 
 가볍고 효율적인 PostgreSQL 클라이언트 라이브러리입니다. Supabase와 동일한 API를 제공하면서도 더 가볍고 빠른 구현을 제공합니다.
 
@@ -267,7 +267,8 @@ const { data, error } = await client
 - `limit(count: number)`: 결과 개수 제한
 - `offset(count: number)`: 결과 시작 위치
 - `range(from: number, to: number)`: 범위 지정
-- `single()`: 단일 결과 반환
+- `single()`: 단일 결과 반환 (결과 없을 시 에러)
+- `maybeSingle()`: 단일 결과 반환 (결과 없을 시 data: null, error: null)
 - `returns<T>()`: 반환 타입 지정
 
 ### 트랜잭션 메소드

package/dist/query-builder.d.ts

@@ -14,7 +14,7 @@ export declare class QueryBuilder<T extends DatabaseSchema, S extends SchemaName
     private limitValue?;
     private offsetValue?;
     private whereValues;
-    private isSingleResult;
+    private singleMode;
     private queryType;
     private insertData?;
     private updateData?;
@@ -27,6 +27,9 @@ export declare class QueryBuilder<T extends DatabaseSchema, S extends SchemaName
         count?: 'exact' | 'planned' | 'estimated';
         head?: boolean;
     }): this;
+    match(conditions: {
+        [key: string]: any;
+    }): this;
     eq(column: string, value: any): this;
     neq(column: string, value: any): this;
     is(column: string, value: any): this;
@@ -39,6 +42,7 @@ export declare class QueryBuilder<T extends DatabaseSchema, S extends SchemaName
     }): this;
     limit(value: number): this;
     offset(value: number): this;
+    maybeSingle(): Promise<SingleQueryResult<Row<T, S, K>>>;
     single(): Promise<SingleQueryResult<Row<T, S, K>>>;
     ilike(column: string, pattern: string): this;
     or(conditions: string): this;

package/dist/query-builder.js

@@ -12,7 +12,7 @@ class QueryBuilder {
         this.orConditions = [];
         this.orderByColumns = [];
         this.whereValues = [];
-        this.isSingleResult = false;
+        this.singleMode = null;
         this.queryType = 'SELECT';
         this.table = table;
         this.schema = schema;
@@ -32,6 +32,13 @@ class QueryBuilder {
         this.headOption = options?.head;
         return this;
     }
+    match(conditions) {
+        for (const key in conditions) {
+            this.whereConditions.push(`"${key}" = $${this.whereValues.length + 1}`);
+            this.whereValues.push(conditions[key]);
+        }
+        return this;
+    }
     eq(column, value) {
         this.whereConditions.push(`"${column}" = $${this.whereValues.length + 1}`);
         this.whereValues.push(value);
@@ -90,8 +97,12 @@ class QueryBuilder {
         this.offsetValue = value;
         return this;
     }
+    maybeSingle() {
+        this.singleMode = 'maybe';
+        return this.execute();
+    }
     single() {
-        this.isSingleResult = true;
+        this.singleMode = 'strict';
         return this.execute();
     }
     ilike(column, pattern) {
@@ -196,7 +207,7 @@ class QueryBuilder {
                 values = [...this.whereValues];
                 break;
             case 'INSERT':
-            case 'UPSERT':
+            case 'UPSERT': {
                 if (!this.insertData)
                     throw new Error('No data provided for insert/upsert');
                 if (Array.isArray(this.insertData)) {
@@ -223,7 +234,8 @@ class QueryBuilder {
                 }
                 query += returning;
                 break;
-            case 'UPDATE':
+            }
+            case 'UPDATE': {
                 if (!this.updateData)
                     throw new Error('No data provided for update');
                 const updateData = { ...this.updateData };
@@ -241,12 +253,14 @@ class QueryBuilder {
                 query += this.buildWhereClause(updateValues);
                 query += returning;
                 break;
-            case 'DELETE':
+            }
+            case 'DELETE': {
                 query = `DELETE FROM ${schemaTable}`;
                 values = [...this.whereValues];
                 query += this.buildWhereClause();
                 query += returning;
                 break;
+            }
         }
         if (this.queryType === 'SELECT') {
             query += this.buildWhereClause();
@@ -293,17 +307,27 @@ class QueryBuilder {
                     statusText: 'Created',
                 };
             }
-            if (this.isSingleResult) {
+            if (this.singleMode) {
                 if (result.rows.length > 1) {
                     return {
                         data: null,
-                        error: new errors_1.PostgresError('Multiple rows returned in single result query'),
+                        error: new errors_1.PostgresError('PGRST114: Multiple rows returned'), // PGRST114: More than one row was returned
                         count: result.rowCount,
-                        status: 406,
-                        statusText: 'Not Acceptable',
+                        status: 406, // Not Acceptable
+                        statusText: 'Not Acceptable. Expected a single row but found multiple.',
                     };
                 }
                 if (result.rows.length === 0) {
+                    if (this.singleMode === 'strict') {
+                        return {
+                            data: null,
+                            error: new errors_1.PostgresError('PGRST116: No rows found'), // PGRST116: Not found
+                            count: 0,
+                            status: 404, // Not Found (more appropriate than 200 for strict single when not found)
+                            statusText: 'Not Found. Expected a single row but found no rows.',
+                        };
+                    }
+                    // this.singleMode === 'maybe'
                     return {
                         data: null,
                         error: null,
@@ -312,6 +336,7 @@ class QueryBuilder {
                         statusText: 'OK',
                     };
                 }
+                // result.rows.length === 1
                 return {
                     data: result.rows[0],
                     error: null,

package/docs/changelog/2025-05-26-maybeSingle-single-refactor.md

@@ -0,0 +1,47 @@
+# Changelog: 2025-05-26
+
+## Feature: `maybeSingle()` Method and `single()` Refactor
+
+**File:** `src/query-builder.ts`
+
+### Summary
+-   The existing `single()` method has been renamed to `maybeSingle()`. This method returns `data: null` and `error: null` if no row is found.
+-   A new `single()` method has been implemented. This method returns `data: null` and an error object (specifically `PostgresError('PGRST116: No rows found')` with status `404`) if no row is found.
+-   Both methods will return an error (`PostgresError('PGRST114: Multiple rows returned')` with status `406`) if multiple rows are returned by the query.
+
+### Detailed Changes
+1.  **Added `singleMode` Property**:
+    *   A new private property `singleMode: 'strict' | 'maybe' | null` was added to the `QueryBuilder` class to manage the behavior of single-row fetching.
+
+2.  **`maybeSingle()` Method (Formerly `single()`)**:
+    *   The original `single()` method was renamed to `maybeSingle()`.
+    *   It now sets `this.singleMode = 'maybe';`.
+    *   In the `execute()` method, when `singleMode` is `'maybe'`:
+        *   If 0 rows are found: returns `{ data: null, error: null, count: 0, status: 200, statusText: 'OK' }`.
+        *   If 1 row is found: returns `{ data: row, error: null, count: 1, status: 200, statusText: 'OK' }`.
+        *   If >1 rows are found: returns `{ data: null, error: new PostgresError('PGRST114: Multiple rows returned'), count: rowCount, status: 406, statusText: 'Not Acceptable. Expected a single row but found multiple.' }`.
+
+3.  **New `single()` Method**:
+    *   A new method named `single()` was introduced.
+    *   It sets `this.singleMode = 'strict';`.
+    *   In the `execute()` method, when `singleMode` is `'strict'`:
+        *   If 0 rows are found: returns `{ data: null, error: new PostgresError('PGRST116: No rows found'), count: 0, status: 404, statusText: 'Not Found. Expected a single row but found no rows.' }`.
+        *   If 1 row is found: returns `{ data: row, error: null, count: 1, status: 200, statusText: 'OK' }`.
+        *   If >1 rows are found: returns `{ data: null, error: new PostgresError('PGRST114: Multiple rows returned'), count: rowCount, status: 406, statusText: 'Not Acceptable. Expected a single row but found multiple.' }`.
+
+4.  **ESLint Fixes in `src/query-builder.ts`**:
+    *   Removed unused type imports `QueryOptions` and `FilterOptions`.
+    *   Scoped lexical declarations within `switch` `case` blocks in `buildQuery()` using `{}`.
+5.  **Unit Tests Added (`src/__tests__/query-builder-single.test.ts`)**:
+    *   Comprehensive Jest tests were added for both `single()` and `maybeSingle()`.
+    *   The test file was initially created in `examples/tests/` and then moved to `src/__tests__/` to align with Jest's `roots` configuration, ensuring test discovery. Import paths within the test file were updated accordingly.
+    *   Tests cover scenarios for finding one row, zero rows, and multiple rows.
+    *   Appropriate assertions for `data`, `error`, `status`, and `statusText` are included.
+    *   Test database setup (`users` and `test_table_for_multi_row` tables) and teardown are handled in `beforeAll`/`afterAll`.
+    *   Type definitions for the test database schema (`TestDatabase`) were created and refined to ensure compatibility and correctness.
+
+### Impact
+-   Developers now have two distinct methods for fetching a single row:
+    -   `maybeSingle()`: Use when a row might or might not exist, and its absence is not an error condition.
+    -   `single()`: Use when a row is expected to exist, and its absence should be treated as an error.
+-   This change provides more explicit control over how "not found" scenarios are handled for single-row queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supalite",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "description": "A lightweight TypeScript PostgreSQL client with Supabase-style API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",