supalite 0.5.5 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.5.6] - 2025-12-17
+
+### 🐞 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,6 +281,7 @@ 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()`: 레코드 삭제

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.js

@@ -280,12 +280,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}"`;
                 }));

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.6",
   "description": "A lightweight TypeScript PostgreSQL client with Supabase-style API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",