supalite 0.7.6 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.8.0] - 2026-01-19
+
+### ✨ Added
+- `bigintTransform: 'number-or-string'` 옵션을 추가했습니다. 안전 범위는 `Number`, 그 외는 문자열을 반환합니다.
+
+### 🔧 Changed
+- `bigintTransform` 기본값을 `'number-or-string'`으로 변경했습니다. (Supabase 기본값과의 호환을 높이기 위함)
+
 ## [0.7.2] - 2026-01-17
 
 ### ✨ Added

package/README.ko.md

@@ -204,7 +204,7 @@ const client = new SupaLitePG<Database>({
   database: 'testdb',
   port: 5432,
   ssl: false,
-  // bigintTransform: 'string', // BIGINT 타입을 문자열로 받기 (기본값: 'bigint')
+  // bigintTransform: 'number-or-string', // 안전 범위는 Number, 그 외는 문자열 (기본값: 'number-or-string')
   // verbose: true // 상세 로그 출력
 });
 
@@ -299,7 +299,7 @@ const client = new SupaLitePG<Database>({
   database: 'testdb',
   port: 5432,
   ssl: false,
-  // bigintTransform: 'string', // BIGINT 타입을 문자열로 받기 (기본값: 'bigint')
+  // bigintTransform: 'number-or-string', // 안전 범위는 Number, 그 외는 문자열 (기본값: 'number-or-string')
   // verbose: true // 상세 로그 출력
 });
 ```
@@ -1083,14 +1083,15 @@ DB_SSL=true
 - `ssl?: boolean`: SSL 연결 사용 여부 (기본값: `false`, 환경 변수: `DB_SSL`).
 - `schema?: string`: 기본 스키마 (기본값: `'public'`).
 - `verbose?: boolean`: 상세 로그 출력 여부 (기본값: `false`, 환경 변수: `SUPALITE_VERBOSE`).
-- `bigintTransform?: 'bigint' | 'string' | 'number'`:
+- `bigintTransform?: 'bigint' | 'string' | 'number' | 'number-or-string'`:
     - 데이터베이스의 `BIGINT` 타입을 어떻게 변환할지 지정합니다.
-    - `'bigint'` (기본값): JavaScript의 네이티브 `BigInt` 객체로 변환합니다. 이 라이브러리의 `Json` 타입은 `bigint`를 포함할 수 있도록 정의되어 있으나, 표준 `JSON.stringify()` 함수는 `BigInt`를 직접 처리하지 못하므로 `TypeError`가 발생할 수 있습니다. `BigInt` 값을 JSON으로 직렬화하려면 사용자 정의 replacer 함수를 사용하거나 사전에 문자열 등으로 변환해야 합니다. JSON/JSONB 입력에서는 `BigInt`를 문자열로 직렬화합니다.
+    - `'bigint'`: JavaScript의 네이티브 `BigInt` 객체로 변환합니다. 이 라이브러리의 `Json` 타입은 `bigint`를 포함할 수 있도록 정의되어 있으나, 표준 `JSON.stringify()` 함수는 `BigInt`를 직접 처리하지 못하므로 `TypeError`가 발생할 수 있습니다. `BigInt` 값을 JSON으로 직렬화하려면 사용자 정의 replacer 함수를 사용하거나 사전에 문자열 등으로 변환해야 합니다. JSON/JSONB 입력에서는 `BigInt`를 문자열로 직렬화합니다.
     - `'string'`: 문자열로 변환합니다. JSON 직렬화에 안전하며, `BigInt`의 전체 정밀도를 유지합니다.
     - `'number'`: JavaScript의 `Number` 타입으로 변환합니다. 값이 `Number.MAX_SAFE_INTEGER` (또는 `Number.MIN_SAFE_INTEGER`)를 초과하면 정밀도 손실이 발생할 수 있습니다. 이 경우 `verbose: true` 설정 시 경고 로그가 출력됩니다. JSON 직렬화에는 안전합니다.
+    - `'number-or-string'` (기본값): 안전 정수 범위면 `Number`로, 범위를 벗어나면 문자열로 반환해 정밀도를 보존합니다.
 
 ### Json 타입과 BigInt
-라이브러리의 내부 `Json` 타입 정의는 `bigint`를 포함하여 TypeScript 코드 내에서 `BigInt` 값을 명시적으로 다룰 수 있도록 합니다. JSON/JSONB 컬럼에 INSERT/UPDATE 할 때는 배열/객체를 stringify하며, 이 과정에서 `BigInt` 값은 문자열로 변환되어 직렬화됩니다. 숫자 JSON이 필요하면 `BigInt`를 `Number`로 변환해 전달하세요(정밀도 주의). 표준 `JSON.stringify()`는 여전히 `BigInt`를 직접 처리하지 못하므로, 사용자 코드에서 직접 직렬화할 때는 replacer가 필요합니다. `bigintTransform` 옵션을 `'string'` 또는 `'number'`로 설정하면 데이터베이스 조회 시점부터 JSON 직렬화에 안전한 형태로 `BIGINT` 값을 받을 수 있습니다.
+라이브러리의 내부 `Json` 타입 정의는 `bigint`를 포함하여 TypeScript 코드 내에서 `BigInt` 값을 명시적으로 다룰 수 있도록 합니다. JSON/JSONB 컬럼에 INSERT/UPDATE 할 때는 배열/객체를 stringify하며, 이 과정에서 `BigInt` 값은 문자열로 변환되어 직렬화됩니다. 숫자 JSON이 필요하면 `BigInt`를 `Number`로 변환해 전달하세요(정밀도 주의). 표준 `JSON.stringify()`는 여전히 `BigInt`를 직접 처리하지 못하므로, 사용자 코드에서 직접 직렬화할 때는 replacer가 필요합니다. `bigintTransform` 옵션을 `'string'`, `'number'`, 또는 `'number-or-string'`로 설정하면 데이터베이스 조회 시점부터 JSON 직렬화에 안전한 형태로 `BIGINT` 값을 받을 수 있습니다.
 
 ## 응답 형식
 

package/README.md

@@ -205,7 +205,7 @@ const client = new SupaLitePG<Database>({
   database: 'testdb',
   port: 5432,
   ssl: false,
-  // bigintTransform: 'string', // receive BIGINT as string (default: 'bigint')
+  // bigintTransform: 'number-or-string', // numbers when safe, strings otherwise (default: 'number-or-string')
   // verbose: true // verbose logging
 });
 
@@ -299,7 +299,7 @@ const client = new SupaLitePG<Database>({
   database: 'testdb',
   port: 5432,
   ssl: false,
-  // bigintTransform: 'string',
+  // bigintTransform: 'number-or-string', // default: 'number-or-string'
   // verbose: true
 });
 ```
@@ -1079,13 +1079,14 @@ DB_SSL=true
 - `ssl?: boolean`: SSL (default: `false`, env: `DB_SSL`)
 - `schema?: string`: default schema (default: `public`)
 - `verbose?: boolean`: verbose logging (default: `false`, env: `SUPALITE_VERBOSE`)
-- `bigintTransform?: 'bigint' | 'string' | 'number'`:
-  - `'bigint'` (default): uses native `BigInt`
+- `bigintTransform?: 'bigint' | 'string' | 'number' | 'number-or-string'`:
+  - `'bigint'`: uses native `BigInt`
   - `'string'`: returns string values (safe for JSON)
   - `'number'`: returns `Number` (may lose precision, warns if unsafe)
+  - `'number-or-string'` (default): returns `Number` when safe; otherwise keeps the string to preserve precision
 
 ### Json type and BigInt
-The internal `Json` type includes `bigint` to allow explicit BigInt usage in TypeScript. When inserting or updating JSON/JSONB columns, SupaLite stringifies arrays/objects and converts any BigInt values to strings to avoid `JSON.stringify()` errors. If you need numeric JSON values, convert BigInt to `Number` yourself (mind precision). Standard `JSON.stringify()` still cannot handle native `BigInt` in userland; use a custom replacer if you serialize objects yourself.
+The internal `Json` type includes `bigint` to allow explicit BigInt usage in TypeScript. When inserting or updating JSON/JSONB columns, SupaLite stringifies arrays/objects and converts any BigInt values to strings to avoid `JSON.stringify()` errors. If you need numeric JSON values, convert BigInt to `Number` yourself (mind precision). Standard `JSON.stringify()` still cannot handle native `BigInt` in userland; use a custom replacer if you serialize objects yourself. For JSON-safe query results without precision loss, use `bigintTransform: 'number-or-string'` so only safe values become numbers.
 
 ## Response format
 

package/SPEC.md

@@ -15,7 +15,7 @@ SupaLite is a lightweight TypeScript PostgreSQL client that mirrors a subset of
 - Accepts either `connectionString` or discrete connection params.
 - Optional `pool` lets callers inject an existing `pg` Pool (SupaLite does not create or close the pool).
 - Env vars supported: `DB_CONNECTION`, `DB_USER`, `DB_HOST`, `DB_NAME`, `DB_PASS`, `DB_PORT`, `DB_SSL`.
-- `bigintTransform`: `'bigint' | 'string' | 'number'` controls how BIGINT values are parsed.
+- `bigintTransform`: `'bigint' | 'string' | 'number' | 'number-or-string'` controls how BIGINT values are parsed.
 - `verbose`: logs SQL, values, and warnings for risky bigint-to-number conversions.
 
 ### 2.2 QueryBuilder
@@ -121,10 +121,11 @@ Notes:
   - Arrays and plain objects are `JSON.stringify`'d, with BigInt values converted to strings.
   - Dates and primitives are passed through.
 - Native arrays (e.g. `text[]`) are passed through as JavaScript arrays.
-- BIGINT parsing:
+- BIGINT parsing (default: 'number-or-string'):
   - `'bigint'`: `BigInt` values.
   - `'string'`: string values.
   - `'number'`: `Number` with precision warning if unsafe.
+  - `'number-or-string'`: `Number` when safe, otherwise string to preserve precision.
 
 ## 6. Transactions
 - `begin`, `commit`, `rollback`, and `transaction` are implemented on `SupaLitePG`.

package/dist/postgres-client.js

@@ -8,6 +8,8 @@ const errors_1 = require("./errors");
 const dotenv_1 = require("dotenv");
 // .env 파일 로드
 (0, dotenv_1.config)();
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
 class RpcBuilder {
     constructor(pool, schema, procedureName, params = {}) {
         this.pool = pool;
@@ -174,7 +176,7 @@ class SupaLitePG {
         this.verbose = false;
         this.ownsPool = true;
         this.verbose = config?.verbose || process.env.SUPALITE_VERBOSE === 'true' || false;
-        this.bigintTransform = config?.bigintTransform || 'bigint'; // 기본값 'bigint'
+        this.bigintTransform = config?.bigintTransform || 'number-or-string'; // 기본값 'number-or-string'
         if (this.verbose) {
             console.log(`[SupaLite VERBOSE] BIGINT transform mode set to: '${this.bigintTransform}'`);
         }
@@ -195,6 +197,21 @@ class SupaLitePG {
                     return num;
                 });
                 break;
+            case 'number-or-string':
+                pg_1.types.setTypeParser(20, (val) => {
+                    if (val === null)
+                        return null;
+                    const bigValue = BigInt(val);
+                    if (bigValue > MAX_SAFE_BIGINT || bigValue < MIN_SAFE_BIGINT) {
+                        if (this.verbose) {
+                            console.warn(`[SupaLite VERBOSE WARNING] BIGINT value ${val} exceeds safe integer range; ` +
+                                'returning string to preserve precision.');
+                        }
+                        return val;
+                    }
+                    return Number(val);
+                });
+                break;
             case 'bigint':
             default: // 기본값 및 'bigint' 명시 시
                 pg_1.types.setTypeParser(20, (val) => val === null ? null : BigInt(val));

package/dist/types.d.ts

@@ -45,7 +45,7 @@ export type UpdateRow<T extends DatabaseSchema, S extends SchemaName<T>, K exten
     updated_at?: string | null;
 } : never;
 export type EnumType<T extends DatabaseSchema, S extends SchemaName<T>, E extends keyof NonNullable<T[S]['Enums']>> = NonNullable<T[S]['Enums']>[E];
-export type BigintTransformType = 'bigint' | 'string' | 'number';
+export type BigintTransformType = 'bigint' | 'string' | 'number' | 'number-or-string';
 export interface SupaliteConfig {
     pool?: Pool;
     connectionString?: string;

package/package.json

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