supalite 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.5.7] - 2026-01-14
+
+### ✨ Added
+- `upsert()`에 `onConflict` 다중 컬럼 지정 지원을 추가했습니다. 이제 콤마 구분 문자열 또는 문자열 배열을 사용할 수 있습니다. (예: `'set_id, name'`, `['set_id', 'name']`)
+
+### 🐞 Fixed
+- `select()`의 PostgREST-style embed(`related_table(*)`)가 **양방향 FK**를 지원하도록 개선했습니다. 이제 1:N 관계는 배열(`[]` 기본값), N:1 관계는 객체(또는 `null`)로 반환합니다. (See [docs/changelog/2025-12-17-embed-many-to-one.md](docs/changelog/2025-12-17-embed-many-to-one.md))
+
 ## [0.5.5] - 2025-11-26
 
 ### ✨ Added

package/README.md

@@ -1,6 +1,6 @@
 # SupaLite
 
-[![npm version](https://img.shields.io/badge/version-0.3.3-blue.svg)](https://www.npmjs.com/package/supalite)
+[![npm version](https://img.shields.io/npm/v/supalite.svg)](https://www.npmjs.com/package/supalite)
 
 가볍고 효율적인 PostgreSQL 클라이언트 라이브러리입니다. Supabase와 동일한 API를 제공하면서도 더 가볍고 빠른 구현을 제공합니다.
 
@@ -213,6 +213,17 @@ const { data, error } = await client
   .from('users')
   .ilike('email', '%@example.com');
 
+// 관계 테이블 조회 (PostgREST-style embed)
+// 1:N 관계는 배열로 반환됩니다 (기본값: [])
+const { data: authors } = await client
+  .from('authors')
+  .select('*, books(*)');
+
+// N:1 관계는 객체로 반환됩니다 (또는 null)
+const { data: books } = await client
+  .from('books')
+  .select('*, authors(*)');
+
 // 정확한 카운트와 함께 조회
 const { data, count, error } = await client
   .from('users')
@@ -270,10 +281,11 @@ const { data, error } = await client
 - `select(columns?: string, options?: { count?: 'exact' | 'planned' | 'estimated', head?: boolean })`: 조회할 컬럼 지정
   - `options.count`: `'exact'`로 설정하면 `limit`의 영향을 받지 않는 전체 결과의 개수를 `count` 속성으로 반환합니다.
   - `options.head`: `true`로 설정하면 데이터 없이 `count`만 가져옵니다. `count` 옵션과 함께 사용하면 효율적으로 전체 개수만 조회할 수 있습니다.
+  - PostgREST-style embed: `select('*, related_table(*)')` 또는 `select('col, related_table(col1, col2)')`
 - `insert(data: T['Tables'][K]['Insert'] | T['Tables'][K]['Insert'][])`: 단일 또는 다중 레코드 삽입
 - `update(data: T['Tables'][K]['Update'])`: 레코드 업데이트
 - `delete()`: 레코드 삭제
-- `upsert(data: T['Tables'][K]['Insert'], options?: { onConflict: string })`: 삽입 또는 업데이트
+- `upsert(data: T['Tables'][K]['Insert'], options?: { onConflict: string | string[] })`: 삽입 또는 업데이트
 
 ### 필터 메소드
 

package/dist/postgres-client.d.ts

@@ -67,6 +67,7 @@ export declare class SupaLitePG<T extends {
     getForeignKey(schema: string, table: string, foreignTable: string): Promise<{
         column: string;
         foreignColumn: string;
+        isArray: boolean;
     } | null>;
     rpc(procedureName: string, params?: Record<string, any>): RpcBuilder;
     testConnection(): Promise<boolean>;

package/dist/postgres-client.js

@@ -329,11 +329,26 @@ class SupaLitePG {
     `;
         const activeClient = this.isTransaction && this.client ? this.client : await this.pool.connect();
         try {
+            // 1) One-to-many: `foreignTable` has a foreign key referencing `table`
+            // e.g. authors <- books.author_id, so embedding books(*) on authors returns an array
             const result = await activeClient.query(query, [schema, foreignTable, table]);
             if (result.rows.length > 0) {
                 const relationship = {
                     column: result.rows[0].foreign_column_name,
                     foreignColumn: result.rows[0].column_name,
+                    isArray: true,
+                };
+                this.foreignKeyCache.set(cacheKey, relationship);
+                return relationship;
+            }
+            // 2) Many-to-one: `table` has a foreign key referencing `foreignTable`
+            // e.g. books.author_id -> authors.id, so embedding authors(*) on books returns an object
+            const reverseResult = await activeClient.query(query, [schema, table, foreignTable]);
+            if (reverseResult.rows.length > 0) {
+                const relationship = {
+                    column: reverseResult.rows[0].column_name,
+                    foreignColumn: reverseResult.rows[0].foreign_column_name,
+                    isArray: false,
                 };
                 this.foreignKeyCache.set(cacheKey, relationship);
                 return relationship;

package/dist/query-builder.d.ts

@@ -57,8 +57,10 @@ export declare class QueryBuilder<T extends DatabaseSchema, S extends SchemaName
     returns<NewS extends SchemaName<T>, NewK extends TableName<T, NewS>>(): QueryBuilder<T, NewS, NewK>;
     range(from: number, to: number): this;
     upsert(values: InsertRow<T, S, K>, options?: {
-        onConflict: string;
+        onConflict: string | string[];
     }): this;
+    private formatConflictTarget;
+    private quoteConflictTargetColumn;
     private shouldReturnData;
     private buildWhereClause;
     private buildQuery;

package/dist/query-builder.js

@@ -234,6 +234,39 @@ class QueryBuilder {
         this.conflictTarget = options?.onConflict;
         return this;
     }
+    formatConflictTarget(target) {
+        if (Array.isArray(target)) {
+            return target
+                .map((column) => this.quoteConflictTargetColumn(column))
+                .filter(Boolean)
+                .join(', ');
+        }
+        const trimmedTarget = target.trim();
+        if (!trimmedTarget) {
+            return trimmedTarget;
+        }
+        if (trimmedTarget.includes('"') || trimmedTarget.includes('(') || trimmedTarget.includes(')')) {
+            return trimmedTarget;
+        }
+        if (trimmedTarget.includes(',')) {
+            return trimmedTarget
+                .split(',')
+                .map((column) => this.quoteConflictTargetColumn(column))
+                .filter(Boolean)
+                .join(', ');
+        }
+        return this.quoteConflictTargetColumn(trimmedTarget);
+    }
+    quoteConflictTargetColumn(column) {
+        const trimmedColumn = column.trim();
+        if (!trimmedColumn) {
+            return trimmedColumn;
+        }
+        if (trimmedColumn.startsWith('"') && trimmedColumn.endsWith('"')) {
+            return trimmedColumn;
+        }
+        return `"${trimmedColumn}"`;
+    }
     shouldReturnData() {
         return this.selectColumns !== null;
     }
@@ -280,12 +313,23 @@ class QueryBuilder {
                         return null;
                     }
                     const foreignSchemaTable = `"${String(this.schema)}"."${join.foreignTable}"`;
+                    if (fk.isArray) {
+                        return `(
+                SELECT COALESCE(json_agg(j), '[]'::json)
+                FROM (
+                  SELECT ${join.columns}
+                  FROM ${foreignSchemaTable}
+                  WHERE "${fk.foreignColumn}" = ${schemaTable}."${fk.column}"
+                ) as j
+              ) as "${join.foreignTable}"`;
+                    }
                     return `(
-              SELECT json_agg(j)
+              SELECT row_to_json(j)
               FROM (
                 SELECT ${join.columns}
                 FROM ${foreignSchemaTable}
                 WHERE "${fk.foreignColumn}" = ${schemaTable}."${fk.column}"
+                LIMIT 1
               ) as j
             ) as "${join.foreignTable}"`;
                 }));
@@ -356,14 +400,13 @@ class QueryBuilder {
                     query = `INSERT INTO ${schemaTable} ("${insertColumns.join('","')}") VALUES (${insertPlaceholders})`;
                 }
                 if (this.queryType === 'UPSERT' && this.conflictTarget) {
-                    // Quote conflict target if it's a simple column name and not already quoted
-                    const conflictTargetSQL = (this.conflictTarget.includes('"') || this.conflictTarget.includes('(') || this.conflictTarget.includes(','))
-                        ? this.conflictTarget
-                        : `"${this.conflictTarget}"`;
-                    query += ` ON CONFLICT (${conflictTargetSQL}) DO UPDATE SET `;
-                    query += insertColumns
-                        .map((col) => `"${col}" = EXCLUDED."${col}"`)
-                        .join(', ');
+                    const conflictTargetSQL = this.formatConflictTarget(this.conflictTarget);
+                    if (conflictTargetSQL) {
+                        query += ` ON CONFLICT (${conflictTargetSQL}) DO UPDATE SET `;
+                        query += insertColumns
+                            .map((col) => `"${col}" = EXCLUDED."${col}"`)
+                            .join(', ');
+                    }
                 }
                 query += returning;
                 break;

package/docs/changelog/2025-12-17-embed-many-to-one.md

@@ -0,0 +1,30 @@
+# PostgREST-style Embed: Many-to-One Support
+
+- **Date**: 2025-12-17
+- **Author**: Codex
+- **Status**: Completed
+
+## Summary
+
+Fixed PostgREST-style embed syntax in `select()` (e.g. `related_table(*)`) so it works for both relationship directions:
+
+- **1:N** (foreign table references the base table) returns an **array** (defaults to `[]`).
+- **N:1** (base table references the foreign table) returns a **single object** (or `null`).
+
+## Changes
+
+1. **Bidirectional FK resolution**
+   - `SupaLitePG.getForeignKey()` now checks both directions between `table` and `foreignTable` and returns whether the embed should be an array or object.
+
+2. **Correct JSON shape in SQL generation**
+   - `QueryBuilder` uses `json_agg` (with `COALESCE(..., '[]'::json)`) for 1:N embeds.
+   - `QueryBuilder` uses `row_to_json` (with `LIMIT 1`) for N:1 embeds.
+
+3. **Unit tests**
+   - Added tests to cover N:1 embed behavior and nested column selection.
+
+## Impact
+
+- Queries like `from('menu_item_opts').select('*, menu_item_opts_schema(*)')` now embed `menu_item_opts_schema` without warnings, matching PostgREST expectations.
+- Existing 1:N embed behavior remains compatible, with an improved empty-result shape (`[]` instead of `null`).
+

package/package.json

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