supalite 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.4.0] - 2025-06-10
+
+### ✨ Added
+-   **Configurable `BIGINT` Transformation**: Introduced `bigintTransform` option in `SupaLitePG` constructor to allow users to specify how `BIGINT` database types are transformed (to `'bigint'`, `'string'`, or `'number'`). Default is `'bigint'`. This provides flexibility and helps mitigate `JSON.stringify` errors with native `BigInt` objects. (See [docs/changelog/2025-06-10-bigint-handling-enhancement.md](docs/changelog/2025-06-10-bigint-handling-enhancement.md) for details)
+
+### 🛠 Changed
+-   The internal `Json` type in `src/types.ts` now explicitly includes `bigint`, with documentation clarifying user responsibility for `JSON.stringify` handling.
+-   Improved client initialization logging for `bigintTransform` mode when `verbose` is enabled.
+
 ## [0.1.8] - 2025-03-04
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # SupaLite
 
-[![npm version](https://img.shields.io/badge/version-0.3.2-blue.svg)](https://www.npmjs.com/package/supalite)
+[![npm version](https://img.shields.io/badge/version-0.3.3-blue.svg)](https://www.npmjs.com/package/supalite)
 
 가볍고 효율적인 PostgreSQL 클라이언트 라이브러리입니다. Supabase와 동일한 API를 제공하면서도 더 가볍고 빠른 구현을 제공합니다.
 
@@ -40,7 +40,9 @@ const client = new SupaLitePG<Database>({
   host: 'localhost',
   database: 'testdb',
   port: 5432,
-  ssl: false
+  ssl: false,
+  // bigintTransform: 'string', // BIGINT 타입을 문자열로 받기 (기본값: 'bigint')
+  // verbose: true // 상세 로그 출력
 });
 
 // 또는 환경 변수 사용
@@ -104,7 +106,9 @@ const client = new SupaLitePG<Database>({
   host: 'localhost',
   database: 'testdb',
   port: 5432,
-  ssl: false
+  ssl: false,
+  // bigintTransform: 'string', // BIGINT 타입을 문자열로 받기 (기본값: 'bigint')
+  // verbose: true // 상세 로그 출력
 });
 ```
 
@@ -231,14 +235,28 @@ const { data, error } = await client
   ]);
 
 // JSONB 배열 데이터 처리
+// 중요: JSON/JSONB 컬럼에 배열을 삽입/업데이트할 경우, 사용자가 직접 JSON.stringify()를 사용해야 합니다.
+// SupaLite는 일반 객체에 대해서만 자동 stringify를 수행합니다.
+const myJsonArray = ['tag1', 2025, { active: true }];
 const { data: jsonData, error: jsonError } = await client
   .from('your_jsonb_table') // 'your_jsonb_table'을 실제 테이블명으로 변경
   .insert({ 
-    metadata_array: ['tag1', 2025, { active: true }] 
+    metadata_array: JSON.stringify(myJsonArray) // 배열은 직접 stringify
   })
   .select('metadata_array')
   .single();
 
+// 네이티브 배열(TEXT[], INTEGER[] 등) 데이터 처리
+// 이 경우, JavaScript 배열을 직접 전달하면 pg 드라이버가 올바르게 처리합니다.
+const { data: nativeArrayData, error: nativeArrayError } = await client
+  .from('your_native_array_table') // 실제 테이블명으로 변경
+  .insert({
+    tags_column: ['tech', 'event'], // TEXT[] 컬럼 예시
+    scores_column: [100, 95, 88]    // INTEGER[] 컬럼 예시
+  })
+  .select('tags_column, scores_column')
+  .single();
+
 // 다른 스키마 사용
 const { data, error } = await client
   .from('users', 'other_schema')
@@ -298,8 +316,31 @@ DB_NAME=your_db_name
 DB_PASS=your_db_password
 DB_PORT=5432
 DB_SSL=true
+# SUPALITE_VERBOSE=true # 상세 로그 출력 활성화
 ```
 
+### SupaLitePG 생성자 옵션
+
+`SupaLitePG` 생성자는 다음 옵션을 받을 수 있습니다:
+
+- `connectionString?: string`: PostgreSQL 연결 문자열 (예: `postgresql://user:password@host:port/database`). 제공되면 다른 연결 매개변수보다 우선합니다.
+- `user?: string`: 데이터베이스 사용자 이름 (환경 변수: `DB_USER`).
+- `host?: string`: 데이터베이스 호스트 (환경 변수: `DB_HOST`).
+- `database?: string`: 데이터베이스 이름 (환경 변수: `DB_NAME`).
+- `password?: string`: 데이터베이스 비밀번호 (환경 변수: `DB_PASS`).
+- `port?: number`: 데이터베이스 포트 (기본값: 5432, 환경 변수: `DB_PORT`).
+- `ssl?: boolean`: SSL 연결 사용 여부 (기본값: `false`, 환경 변수: `DB_SSL`).
+- `schema?: string`: 기본 스키마 (기본값: `'public'`).
+- `verbose?: boolean`: 상세 로그 출력 여부 (기본값: `false`, 환경 변수: `SUPALITE_VERBOSE`).
+- `bigintTransform?: 'bigint' | 'string' | 'number'`:
+    - 데이터베이스의 `BIGINT` 타입을 어떻게 변환할지 지정합니다.
+    - `'bigint'` (기본값): JavaScript의 네이티브 `BigInt` 객체로 변환합니다. 이 라이브러리의 `Json` 타입은 `bigint`를 포함할 수 있도록 정의되어 있으나, 표준 `JSON.stringify()` 함수는 `BigInt`를 직접 처리하지 못하므로 `TypeError`가 발생할 수 있습니다. `BigInt` 값을 JSON으로 직렬화하려면 사용자 정의 replacer 함수를 사용하거나 사전에 문자열 등으로 변환해야 합니다.
+    - `'string'`: 문자열로 변환합니다. JSON 직렬화에 안전하며, `BigInt`의 전체 정밀도를 유지합니다.
+    - `'number'`: JavaScript의 `Number` 타입으로 변환합니다. 값이 `Number.MAX_SAFE_INTEGER` (또는 `Number.MIN_SAFE_INTEGER`)를 초과하면 정밀도 손실이 발생할 수 있습니다. 이 경우 `verbose: true` 설정 시 경고 로그가 출력됩니다. JSON 직렬화에는 안전합니다.
+
+### Json 타입과 BigInt
+라이브러리의 내부 `Json` 타입 정의는 `bigint`를 포함하여 TypeScript 코드 내에서 `BigInt` 값을 명시적으로 다룰 수 있도록 합니다. 그러나 `Json` 타입의 데이터를 표준 `JSON.stringify()`로 직렬화할 때, 포함된 `BigInt` 객체는 특별한 처리(예: 사용자 정의 replacer 함수 또는 사전 문자열 변환)가 필요합니다. `bigintTransform` 옵션을 `'string'` 또는 `'number'`로 설정하면 데이터베이스 조회 시점부터 JSON 직렬화에 안전한 형태로 `BIGINT` 값을 받을 수 있습니다.
+
 ## 응답 형식
 
 모든 쿼리 메소드는 다음과 같은 형식의 응답을 반환합니다:

package/dist/postgres-client.d.ts

@@ -26,6 +26,9 @@ export declare class SupaLitePG<T extends {
     private client;
     private isTransaction;
     private schema;
+    private schemaCache;
+    verbose: boolean;
+    private bigintTransform;
     constructor(config?: SupaliteConfig);
     begin(): Promise<void>;
     commit(): Promise<void>;
@@ -37,6 +40,7 @@ export declare class SupaLitePG<T extends {
     from<S extends keyof T, K extends TableOrViewName<T, S>>(table: K, schema: S): QueryBuilder<T, S, K> & Promise<QueryResult<Row<T, S, K>>> & {
         single(): Promise<SingleQueryResult<Row<T, S, K>>>;
     };
+    getColumnPgType(dbSchema: string, tableName: string, columnName: string): Promise<string | undefined>;
     rpc(procedureName: string, params?: Record<string, any>): Promise<{
         data: any;
         error: PostgresError | null;

package/dist/postgres-client.js

@@ -1,68 +1,88 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.supalitePg = exports.SupaLitePG = void 0;
-const pg_1 = require("pg");
+const pg_1 = require("pg"); // PoolConfig 추가
 const query_builder_1 = require("./query-builder");
 const errors_1 = require("./errors");
 const dotenv_1 = require("dotenv");
 // .env 파일 로드
 (0, dotenv_1.config)();
-// bigint 타입(OID: 20)을 JavaScript의 BigInt로 변환하는 파서 등록
-pg_1.types.setTypeParser(20, function (val) {
-    return val === null ? null : BigInt(val);
-});
 class SupaLitePG {
     constructor(config) {
         this.client = null;
         this.isTransaction = false;
+        this.schemaCache = new Map(); // schemaName.tableName -> Map<columnName, pgDataType>
+        this.verbose = false;
+        this.verbose = config?.verbose || process.env.SUPALITE_VERBOSE === 'true' || false;
+        this.bigintTransform = config?.bigintTransform || 'bigint'; // 기본값 'bigint'
+        if (this.verbose) {
+            console.log(`[SupaLite VERBOSE] BIGINT transform mode set to: '${this.bigintTransform}'`);
+        }
+        // 타입 파서 설정
+        switch (this.bigintTransform) {
+            case 'string':
+                pg_1.types.setTypeParser(20, (val) => val === null ? null : val); // pg는 이미 문자열로 줌
+                break;
+            case 'number':
+                pg_1.types.setTypeParser(20, (val) => {
+                    if (val === null)
+                        return null;
+                    const num = Number(val);
+                    if (this.verbose && (num > Number.MAX_SAFE_INTEGER || num < Number.MIN_SAFE_INTEGER)) {
+                        console.warn(`[SupaLite VERBOSE WARNING] BIGINT value ${val} converted to Number might lose precision. ` +
+                            `Max safe integer is ${Number.MAX_SAFE_INTEGER}.`);
+                    }
+                    return num;
+                });
+                break;
+            case 'bigint':
+            default: // 기본값 및 'bigint' 명시 시
+                pg_1.types.setTypeParser(20, (val) => val === null ? null : BigInt(val));
+                break;
+        }
+        let poolConfigOptions = {};
         // connectionString이 제공되면 이를 우선 사용
         if (config?.connectionString || process.env.DB_CONNECTION) {
             try {
                 const connectionString = config?.connectionString || process.env.DB_CONNECTION || '';
-                // 간단한 유효성 검사 (postgresql:// 로 시작하는지)
                 if (!connectionString.startsWith('postgresql://')) {
                     throw new Error('Invalid PostgreSQL connection string format. Must start with postgresql://');
                 }
-                this.pool = new pg_1.Pool({
-                    connectionString,
-                    ssl: config?.ssl !== undefined ? config.ssl : process.env.DB_SSL === 'true'
-                });
-                // 스키마 설정
-                this.schema = config?.schema || 'public';
-                // 디버그용 로그
-                console.log('Database connection using connection string');
-                // Error handling
-                this.pool.on('error', (err) => {
-                    console.error('Unexpected error on idle client', err);
-                    process.exit(-1);
-                });
-                return;
+                poolConfigOptions.connectionString = connectionString;
+                poolConfigOptions.ssl = config?.ssl !== undefined ? config.ssl : process.env.DB_SSL === 'true';
+                if (this.verbose) {
+                    console.log('[SupaLite VERBOSE] Database connection using connection string');
+                }
             }
             catch (err) {
-                console.error('Database connection error:', err.message);
+                console.error('[SupaLite ERROR] Database connection error:', err.message);
                 throw new Error(`Failed to establish database connection: ${err.message}`);
             }
         }
-        // 기존 코드: 개별 매개변수 사용
-        const poolConfig = {
-            user: config?.user || process.env.DB_USER,
-            host: config?.host || process.env.DB_HOST,
-            database: config?.database || process.env.DB_NAME,
-            password: config?.password || process.env.DB_PASS,
-            port: config?.port || Number(process.env.DB_PORT) || 5432,
-            ssl: config?.ssl || process.env.DB_SSL === 'true',
-        };
+        else {
+            // 기존 코드: 개별 매개변수 사용
+            poolConfigOptions = {
+                user: config?.user || process.env.DB_USER,
+                host: config?.host || process.env.DB_HOST,
+                database: config?.database || process.env.DB_NAME,
+                password: config?.password || process.env.DB_PASS,
+                port: config?.port || Number(process.env.DB_PORT) || 5432,
+                ssl: config?.ssl !== undefined ? config.ssl : process.env.DB_SSL === 'true', // ssl 설정 명시적 처리
+            };
+            if (this.verbose) {
+                console.log('[SupaLite VERBOSE] Database connection using individual parameters:', {
+                    ...poolConfigOptions,
+                    password: '********'
+                });
+            }
+        }
+        this.pool = new pg_1.Pool(poolConfigOptions);
         this.schema = config?.schema || 'public';
-        // 디버그용 로그 (비밀번호는 제외)
-        console.log('Database connection config:', {
-            ...poolConfig,
-            password: '********'
-        });
-        this.pool = new pg_1.Pool(poolConfig);
         // Error handling
         this.pool.on('error', (err) => {
-            console.error('Unexpected error on idle client', err);
-            process.exit(-1);
+            console.error('[SupaLite ERROR] Unexpected error on idle client', err);
+            // Consider if process.exit is too drastic for a library. Maybe re-throw or emit an event.
+            // process.exit(-1); 
         });
     }
     // 트랜잭션 시작
@@ -105,7 +125,58 @@ class SupaLitePG {
         }
     }
     from(table, schema) {
-        return new query_builder_1.QueryBuilder(this.pool, table, schema || 'public');
+        // QueryBuilder constructor will be updated to accept these arguments
+        return new query_builder_1.QueryBuilder(// Use 'as any' temporarily if QueryBuilder constructor not yet updated
+        this.pool, this, // Pass the SupaLitePG instance itself
+        table, schema || 'public', this.verbose // Pass verbose setting
+        );
+    }
+    async getColumnPgType(dbSchema, tableName, columnName) {
+        const tableKey = `${dbSchema}.${tableName}`;
+        if (this.verbose)
+            console.log(`[SupaLite VERBOSE] getColumnPgType called for ${tableKey}.${columnName}`);
+        let tableInfo = this.schemaCache.get(tableKey);
+        if (!tableInfo) {
+            if (this.verbose)
+                console.log(`[SupaLite VERBOSE] Cache miss for table ${tableKey}. Querying information_schema.`);
+            try {
+                const query = `
+          SELECT column_name, data_type 
+          FROM information_schema.columns 
+          WHERE table_schema = $1 AND table_name = $2;
+        `;
+                // Use a temporary client from the pool for this schema query
+                // if not in a transaction, or use the transaction client if in one.
+                const activeClient = this.isTransaction && this.client ? this.client : await this.pool.connect();
+                try {
+                    const result = await activeClient.query(query, [dbSchema, tableName]);
+                    tableInfo = new Map();
+                    result.rows.forEach((row) => {
+                        tableInfo.set(row.column_name, row.data_type.toLowerCase());
+                    });
+                    this.schemaCache.set(tableKey, tableInfo);
+                    if (this.verbose)
+                        console.log(`[SupaLite VERBOSE] Cached schema for ${tableKey}:`, tableInfo);
+                }
+                finally {
+                    if (!(this.isTransaction && this.client)) { // Only release if it's a temp client not managed by transaction
+                        activeClient.release(); // Cast to any if 'release' is not on type PoolClient from transaction
+                    }
+                }
+            }
+            catch (err) {
+                console.error(`[SupaLite ERROR] Failed to query information_schema for ${tableKey}:`, err.message);
+                return undefined;
+            }
+        }
+        else {
+            if (this.verbose)
+                console.log(`[SupaLite VERBOSE] Cache hit for table ${tableKey}.`);
+        }
+        const pgType = tableInfo?.get(columnName);
+        if (this.verbose)
+            console.log(`[SupaLite VERBOSE] pgType for ${tableKey}.${columnName}: ${pgType}`);
+        return pgType;
     }
     async rpc(procedureName, params = {}) {
         try {

package/dist/query-builder.d.ts

@@ -1,4 +1,5 @@
 import { Pool } from 'pg';
+import type { SupaLitePG } from './postgres-client';
 import { TableName, TableOrViewName, QueryResult, SingleQueryResult, DatabaseSchema, SchemaName, Row, InsertRow, UpdateRow } from './types';
 export declare class QueryBuilder<T extends DatabaseSchema, S extends SchemaName<T> = 'public', K extends TableOrViewName<T, S> = TableOrViewName<T, S>> implements Promise<QueryResult<Row<T, S, K>> | SingleQueryResult<Row<T, S, K>>> {
     private pool;
@@ -19,7 +20,10 @@ export declare class QueryBuilder<T extends DatabaseSchema, S extends SchemaName
     private insertData?;
     private updateData?;
     private conflictTarget?;
-    constructor(pool: Pool, table: K, schema?: S);
+    private client;
+    private verbose;
+    constructor(pool: Pool, client: SupaLitePG<T>, // Accept SupaLitePG instance
+    table: K, schema?: S, verbose?: boolean);
     then<TResult1 = QueryResult<Row<T, S, K>> | SingleQueryResult<Row<T, S, K>>, TResult2 = never>(onfulfilled?: ((value: QueryResult<Row<T, S, K>> | SingleQueryResult<Row<T, S, K>>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<QueryResult<Row<T, S, K>> | SingleQueryResult<Row<T, S, K>> | TResult>;
     finally(onfinally?: (() => void) | null): Promise<QueryResult<Row<T, S, K>> | SingleQueryResult<Row<T, S, K>>>;

package/dist/query-builder.js

@@ -4,7 +4,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryBuilder = void 0;
 const errors_1 = require("./errors");
 class QueryBuilder {
-    constructor(pool, table, schema = 'public') {
+    constructor(pool, client, // Accept SupaLitePG instance
+    table, schema = 'public', verbose = false // Accept verbose setting
+    ) {
         this.pool = pool;
         this[_a] = 'QueryBuilder';
         this.selectColumns = null;
@@ -14,8 +16,11 @@ class QueryBuilder {
         this.whereValues = [];
         this.singleMode = null;
         this.queryType = 'SELECT';
+        this.verbose = false;
+        this.client = client;
         this.table = table;
         this.schema = schema;
+        this.verbose = verbose;
     }
     then(onfulfilled, onrejected) {
         return this.execute().then(onfulfilled, onrejected);
@@ -195,7 +200,7 @@ class QueryBuilder {
         }
         return ' WHERE ' + conditions.join(' AND ');
     }
-    buildQuery() {
+    async buildQuery() {
         let query = '';
         let values = [];
         let insertColumns = [];
@@ -223,32 +228,45 @@ class QueryBuilder {
                     if (rows.length === 0)
                         throw new Error('Empty array provided for insert');
                     insertColumns = Object.keys(rows[0]);
-                    // Process each row for potential JSON stringification
-                    const processedRowsValues = rows.map(row => Object.values(row).map(val => {
-                        if (typeof val === 'bigint') {
-                            return val.toString();
-                        }
-                        if (Array.isArray(val) || (val !== null && typeof val === 'object' && !(val instanceof Date))) {
-                            return JSON.stringify(val);
+                    const processedRowsValuesPromises = rows.map(async (row) => {
+                        const rowValues = [];
+                        for (const colName of insertColumns) { // Ensure order of values matches order of columns
+                            const val = row[colName];
+                            const pgType = await this.client.getColumnPgType(String(this.schema), String(this.table), colName);
+                            if (typeof val === 'bigint') {
+                                rowValues.push(val.toString());
+                            }
+                            else if ((pgType === 'json' || pgType === 'jsonb') &&
+                                (Array.isArray(val) || (val !== null && typeof val === 'object' && !(val instanceof Date)))) {
+                                rowValues.push(JSON.stringify(val));
+                            }
+                            else {
+                                rowValues.push(val);
+                            }
                         }
-                        return val;
-                    }));
-                    values = processedRowsValues.flat();
+                        return rowValues;
+                    });
+                    const processedRowsValuesArrays = await Promise.all(processedRowsValuesPromises);
+                    values = processedRowsValuesArrays.flat();
                     const placeholders = rows.map((_, i) => `(${insertColumns.map((_, j) => `$${i * insertColumns.length + j + 1}`).join(',')})`).join(',');
                     query = `INSERT INTO ${schemaTable} ("${insertColumns.join('","')}") VALUES ${placeholders}`;
                 }
                 else {
                     const insertData = this.insertData;
                     insertColumns = Object.keys(insertData);
-                    values = Object.values(insertData).map(val => {
+                    const valuePromises = insertColumns.map(async (colName) => {
+                        const val = insertData[colName];
+                        const pgType = await this.client.getColumnPgType(String(this.schema), String(this.table), colName);
                         if (typeof val === 'bigint') {
                             return val.toString();
                         }
-                        if (Array.isArray(val) || (val !== null && typeof val === 'object' && !(val instanceof Date))) {
+                        if ((pgType === 'json' || pgType === 'jsonb') &&
+                            (Array.isArray(val) || (val !== null && typeof val === 'object' && !(val instanceof Date)))) {
                             return JSON.stringify(val);
                         }
                         return val;
                     });
+                    values = await Promise.all(valuePromises);
                     const insertPlaceholders = values.map((_, i) => `$${i + 1}`).join(',');
                     query = `INSERT INTO ${schemaTable} ("${insertColumns.join('","')}") VALUES (${insertPlaceholders})`;
                 }
@@ -276,16 +294,21 @@ class QueryBuilder {
                 if ('updated_at' in updateData && !updateData.updated_at) {
                     updateData.updated_at = now;
                 }
-                const processedUpdateValues = Object.values(updateData).map(val => {
+                const updateColumns = Object.keys(updateData);
+                const processedUpdateValuesPromises = updateColumns.map(async (colName) => {
+                    const val = updateData[colName];
+                    const pgType = await this.client.getColumnPgType(String(this.schema), String(this.table), colName);
                     if (typeof val === 'bigint') {
                         return val.toString();
                     }
-                    if (Array.isArray(val) || (val !== null && typeof val === 'object' && !(val instanceof Date))) {
+                    if ((pgType === 'json' || pgType === 'jsonb') &&
+                        (Array.isArray(val) || (val !== null && typeof val === 'object' && !(val instanceof Date)))) {
                         return JSON.stringify(val);
                     }
                     return val;
                 });
-                const setColumns = Object.keys(updateData).map((key, index) => `"${String(key)}" = $${index + 1}`);
+                const processedUpdateValues = await Promise.all(processedUpdateValuesPromises);
+                const setColumns = updateColumns.map((key, index) => `"${String(key)}" = $${index + 1}`);
                 query = `UPDATE ${schemaTable} SET ${setColumns.join(', ')}`;
                 values = [...processedUpdateValues, ...this.whereValues];
                 query += this.buildWhereClause(processedUpdateValues);
@@ -316,7 +339,11 @@ class QueryBuilder {
     }
     async execute() {
         try {
-            const { query, values } = this.buildQuery();
+            const { query, values } = await this.buildQuery(); // await buildQuery
+            if (this.verbose) {
+                console.log('[SupaLite VERBOSE] SQL:', query);
+                console.log('[SupaLite VERBOSE] Values:', values);
+            }
             const result = await this.pool.query(query, values);
             if (this.queryType === 'DELETE' && !this.shouldReturnData()) {
                 return {
@@ -392,6 +419,9 @@ class QueryBuilder {
             };
         }
         catch (err) {
+            if (this.verbose) {
+                console.error('[SupaLite VERBOSE] Error:', err);
+            }
             return {
                 data: [],
                 error: new errors_1.PostgresError(err.message),

package/dist/types.d.ts

@@ -44,8 +44,10 @@ 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 interface SupaliteConfig {
     connectionString?: string;
+    bigintTransform?: BigintTransformType;
     user?: string;
     host?: string;
     database?: string;
@@ -53,6 +55,7 @@ export interface SupaliteConfig {
     port?: number;
     ssl?: boolean;
     schema?: string;
+    verbose?: boolean;
 }
 export type QueryType = 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'UPSERT';
 export interface QueryOptions {

package/docs/changelog/2025-06-10-bigint-handling-enhancement.md

@@ -0,0 +1,35 @@
+# Changelog - 2025-06-10: Enhanced BIGINT Handling
+
+## Summary
+This update introduces a flexible mechanism for handling `BIGINT` data types retrieved from PostgreSQL, addressing potential `TypeError` issues during JSON serialization and providing users with more control over type conversion.
+
+## Changes
+
+### ✨ New Features
+*   **Configurable `BIGINT` Transformation**:
+    *   Added a new `bigintTransform` option to the `SupaLitePG` constructor configuration (`SupaliteConfig`).
+    *   This option allows users to specify how `BIGINT` (OID 20) database columns should be transformed when read.
+    *   Possible values for `bigintTransform`:
+        *   `'bigint'` (Default): Converts `BIGINT` values to native JavaScript `BigInt` objects. This maintains precision but can cause issues with direct `JSON.stringify()` if not handled.
+        *   `'string'`: Converts `BIGINT` values to JavaScript strings. This is safe for JSON serialization and preserves the original value as text.
+        *   `'number'`: Converts `BIGINT` values to JavaScript `Number` objects. This is convenient for smaller numbers but may lead to precision loss for values exceeding `Number.MAX_SAFE_INTEGER` or `Number.MIN_SAFE_INTEGER`. A warning is logged via `console.warn` if `verbose: true` and potential precision loss is detected.
+    *   The chosen transformation mode is logged to the console if `verbose: true` during client initialization.
+
+### 🛠 Improvements
+*   **Type Definitions**:
+    *   The `Json` type in `src/types.ts` now explicitly includes `bigint`. This allows TypeScript to correctly type-check structures that may contain `BigInt` values. Users are reminded (via documentation) that standard `JSON.stringify` will require special handling for `BigInt` objects (e.g., a custom replacer or pre-conversion to string/number).
+*   **Client Initialization**:
+    *   Refined `Pool` initialization in `src/postgres-client.ts` to more consistently use `PoolConfig` for both connection string and individual parameter setups.
+    *   Standardized some internal logging prefixes for verbosity and errors.
+
+### 📄 Documentation
+*   Updated `README.md` to include:
+    *   Detailed explanation of the new `bigintTransform` constructor option, its possible values, default behavior, and implications (especially the precision loss warning for the `'number'` option).
+    *   Clarification in `README.md` regarding the `Json` type including `bigint` and the user's responsibility for `JSON.stringify` handling of `BigInt` objects.
+    *   Examples of using `bigintTransform` and `verbose` options in the `SupaLitePG` constructor.
+    *   Mention of `SUPALITE_VERBOSE=true` as an environment variable option.
+
+## Impact
+-   **Error Resolution**: Users experiencing `TypeError: Do not know how to serialize a BigInt` can now resolve this by setting `bigintTransform: 'string'` or `bigintTransform: 'number'` in the `SupaLitePG` configuration.
+-   **Flexibility**: Provides developers with greater control over how large integer types are handled, catering to different use cases (e.g., precise arithmetic vs. simple display/serialization).
+-   **Backward Compatibility**: The default behavior (`'bigint'`) remains unchanged, minimizing impact on existing users who might rely on receiving `BigInt` objects, though they should be aware of JSON serialization implications.

package/docs/changelog/2025-06-10-jsonb-array-test.md

@@ -4,9 +4,22 @@
     - Updated `JsonbTestTable` related types to use the global `Json` type.
     - Added `another_json_field` (JSONB) to `jsonb_test_table` schema and tests.
     - Modified `beforeAll` to `DROP TABLE IF EXISTS jsonb_test_table` before `CREATE TABLE` to ensure schema updates are applied, fixing a "column does not exist" error during tests.
-    - Removed explicit `JSON.stringify()` from test cases, relying on internal handling.
+    - Removed explicit `JSON.stringify()` from test cases, as this is now handled automatically by `QueryBuilder` based on schema information.
     - Added a new test case for inserting/selecting an object into `another_json_field`.
-- Modified `src/query-builder.ts` (`buildQuery` method):
-    - Implemented automatic `JSON.stringify()` for array or object values (excluding `Date` instances) when preparing data for `INSERT`, `UPSERT`, and `UPDATE` operations. This allows users to pass JavaScript objects/arrays directly for `json`/`jsonb` columns.
-    - Corrected a TypeScript error (`Cannot find name 'updateValues'`) in the `UPDATE` case of `buildQuery`.
-- Ensured `src/types.ts` contains the `Json` type definition.
+    - Added a test case for inserting an empty JavaScript array `[]` into a `jsonb` field, now handled automatically.
+- Modified `src/postgres-client.ts`:
+    - Added `schemaCache` to store column type information fetched from `information_schema.columns`.
+    - Implemented `getColumnPgType(schema, table, column)` method to retrieve (and cache) PostgreSQL data types for columns.
+    - Added `verbose` option to `SupaliteConfig` and `SupaLitePG` for logging.
+    - Modified `from()` method to pass `SupaLitePG` instance and `verbose` setting to `QueryBuilder`.
+- Modified `src/query-builder.ts`:
+    - Updated constructor to accept `SupaLitePG` client instance and `verbose` setting.
+    - Made `buildQuery()` method `async`.
+    - Implemented schema-aware value processing in `buildQuery()` for `INSERT`, `UPSERT`, and `UPDATE`:
+        - Uses `client.getColumnPgType()` to get the PostgreSQL type of each column.
+        - If `pgType` is 'json' or 'jsonb', JavaScript objects and arrays are `JSON.stringify()`'d.
+        - If `pgType` is 'bigint', JavaScript `BigInt`s are `toString()`'d.
+        - Otherwise (e.g., for `text[]`, `integer[]`), values (including JavaScript arrays) are passed as-is to the `pg` driver.
+    - Updated `execute()` method to `await buildQuery()` and include verbose logging for SQL and values if enabled.
+- Ensured `src/types.ts` contains the `Json` type and `verbose` option in `SupaliteConfig`.
+- **Outcome**: `QueryBuilder` now intelligently handles serialization for `json`/`jsonb`, `bigint`, and native array types based on runtime schema information, providing a more seamless experience similar to `supabase-js`. All related tests pass.

package/package.json

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