supalite 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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
+-   `rpc()` 메서드 호출 시 `.single()` 및 `.maybeSingle()` 메서드 체이닝 지원을 추가했습니다. 이를 통해 RPC 결과에 대해 단일 행 제약 조건을 적용할 수 있습니다. (See [docs/changelog/2025-11-26-rpc-single-support.md](docs/changelog/2025-11-26-rpc-single-support.md))
+
 ## [0.5.2] - 2025-10-16
 
 ### 🐞 Fixed

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

@@ -1,3 +1,4 @@
+import { Pool } from 'pg';
 import { QueryBuilder } from './query-builder';
 import { PostgresError } from './errors';
 import { TableOrViewName, SupaliteConfig, Row, QueryResult, SingleQueryResult } from './types';
@@ -19,6 +20,27 @@ type SchemaWithTables = {
     Enums?: any;
     CompositeTypes?: any;
 };
+export declare class RpcBuilder implements Promise<any> {
+    private pool;
+    private schema;
+    private procedureName;
+    private params;
+    readonly [Symbol.toStringTag] = "RpcBuilder";
+    private singleMode;
+    constructor(pool: Pool, schema: string, procedureName: string, params?: Record<string, any>);
+    single(): this;
+    maybeSingle(): this;
+    then<TResult1 = any, TResult2 = never>(onfulfilled?: ((value: any) => 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<any | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<any>;
+    execute(): Promise<{
+        data: any;
+        error: PostgresError | null;
+        count?: number | null;
+        status?: number;
+        statusText?: string;
+    }>;
+}
 export declare class SupaLitePG<T extends {
     [K: string]: SchemaWithTables;
 }> {
@@ -45,14 +67,9 @@ 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>): Promise<{
-        data: any;
-        error: PostgresError | null;
-        count?: number | null;
-        status?: number;
-        statusText?: string;
-    }>;
+    rpc(procedureName: string, params?: Record<string, any>): RpcBuilder;
     testConnection(): Promise<boolean>;
     close(): Promise<void>;
 }

package/dist/postgres-client.js

@@ -1,12 +1,139 @@
 "use strict";
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.supalitePg = exports.SupaLitePG = void 0;
+exports.supalitePg = exports.SupaLitePG = exports.RpcBuilder = void 0;
 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)();
+class RpcBuilder {
+    constructor(pool, schema, procedureName, params = {}) {
+        this.pool = pool;
+        this.schema = schema;
+        this.procedureName = procedureName;
+        this.params = params;
+        this[_a] = 'RpcBuilder';
+        this.singleMode = null;
+    }
+    single() {
+        this.singleMode = 'strict';
+        return this;
+    }
+    maybeSingle() {
+        this.singleMode = 'maybe';
+        return this;
+    }
+    then(onfulfilled, onrejected) {
+        return this.execute().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.execute().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.execute().finally(onfinally);
+    }
+    async execute() {
+        try {
+            const paramNames = Object.keys(this.params);
+            const paramValues = Object.values(this.params);
+            const paramPlaceholders = paramNames.length > 0
+                ? paramNames.map((name, i) => `"${name}" := $${i + 1}`).join(', ')
+                : '';
+            const query = paramPlaceholders
+                ? `SELECT * FROM "${this.schema}"."${this.procedureName}"(${paramPlaceholders})`
+                : `SELECT * FROM "${this.schema}"."${this.procedureName}"()`;
+            const result = await this.pool.query(query, paramValues);
+            // Handle scalar return values (Supabase special handling)
+            // If result has 1 row and 1 column, and we are not in strict table mode (which rpc generally isn't),
+            // we check if it looks like a scalar return.
+            // However, if single() is called, we must respect row constraints.
+            let data = result.rows;
+            // Unwrapping logic for scalar functions (legacy Supabase behavior emulation)
+            // If it returns a single row with a single column, treat as scalar IF not forcing array via logic.
+            // But here we'll stick to basic row handling first, then apply singleMode.
+            // NOTE: Original logic had:
+            // if (result.rows.length === 1 && Object.keys(result.rows[0]).length === 1) { ... return single value ... }
+            // This implies unwrapping happens by default if it looks like a scalar.
+            const isScalarCandidate = result.rows.length === 1 && Object.keys(result.rows[0]).length === 1;
+            if (this.singleMode) {
+                if (result.rows.length > 1) {
+                    return {
+                        data: null,
+                        error: new errors_1.PostgresError('PGRST114: Multiple rows returned'),
+                        count: null,
+                        status: 406,
+                        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'),
+                            count: null,
+                            status: 404,
+                            statusText: 'Not Found. Expected a single row but found no rows.'
+                        };
+                    }
+                    // maybeSingle -> null data, no error
+                    return {
+                        data: null,
+                        error: null,
+                        count: 0,
+                        status: 200,
+                        statusText: 'OK'
+                    };
+                }
+                // 1 row found
+                // Check for scalar unwrapping
+                if (Object.keys(result.rows[0]).length === 1) {
+                    data = Object.values(result.rows[0])[0];
+                }
+                else {
+                    data = result.rows[0];
+                }
+                return {
+                    data,
+                    error: null,
+                    count: 1,
+                    status: 200,
+                    statusText: 'OK'
+                };
+            }
+            // Default behavior (no .single() called)
+            if (isScalarCandidate) {
+                data = Object.values(result.rows[0])[0];
+                return {
+                    data,
+                    error: null,
+                    count: 1,
+                    status: 200,
+                    statusText: 'OK'
+                };
+            }
+            return {
+                data: result.rows.length > 0 ? result.rows : null,
+                error: null,
+                count: result.rowCount,
+                status: 200,
+                statusText: 'OK'
+            };
+        }
+        catch (err) {
+            return {
+                data: null,
+                error: new errors_1.PostgresError(err.message, err.code),
+                count: null,
+                status: 500,
+                statusText: 'Internal Server Error'
+            };
+        }
+    }
+}
+exports.RpcBuilder = RpcBuilder;
+_a = Symbol.toStringTag;
 class SupaLitePG {
     constructor(config) {
         this.client = null;
@@ -202,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;
@@ -220,44 +362,8 @@ class SupaLitePG {
         this.foreignKeyCache.set(cacheKey, null);
         return null;
     }
-    async rpc(procedureName, params = {}) {
-        try {
-            const paramNames = Object.keys(params);
-            const paramValues = Object.values(params);
-            const paramPlaceholders = paramNames.length > 0
-                ? paramNames.map((name, i) => `"${name}" := $${i + 1}`).join(', ')
-                : '';
-            const query = paramPlaceholders
-                ? `SELECT * FROM "${this.schema}"."${procedureName}"(${paramPlaceholders})`
-                : `SELECT * FROM "${this.schema}"."${procedureName}"()`;
-            const result = await this.pool.query(query, paramValues);
-            if (result.rows.length === 1 && Object.keys(result.rows[0]).length === 1) {
-                const singleValue = Object.values(result.rows[0])[0];
-                return {
-                    data: singleValue,
-                    error: null,
-                    count: 1,
-                    status: 200,
-                    statusText: 'OK'
-                };
-            }
-            return {
-                data: result.rows.length > 0 ? result.rows : null,
-                error: null,
-                count: result.rowCount,
-                status: 200,
-                statusText: 'OK'
-            };
-        }
-        catch (err) {
-            return {
-                data: null,
-                error: new errors_1.PostgresError(err.message, err.code),
-                count: null,
-                status: 500,
-                statusText: 'Internal Server Error'
-            };
-        }
+    rpc(procedureName, params = {}) {
+        return new RpcBuilder(this.pool, this.schema, procedureName, params);
     }
     // 연결 테스트 메서드
     async testConnection() {

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-11-26-rpc-single-support.md

@@ -0,0 +1,29 @@
+# RPC .single() and .maybeSingle() Support
+
+- **Date**: 2025-11-26
+- **Author**: Cline
+- **Status**: Completed
+
+## Summary
+
+Implemented `.single()` and `.maybeSingle()` method chaining support for `rpc` calls in `SupaLitePG`. This brings the `rpc` method closer to the Supabase JS client API, allowing users to enforce single-row constraints on RPC results.
+
+## Changes
+
+1.  **Refactored `rpc` Method**:
+    - The `rpc` method in `src/postgres-client.ts` now returns an instance of `RpcBuilder` instead of a `Promise` directly.
+    - `RpcBuilder` implements the `Promise` interface, ensuring backward compatibility for `await rpc(...)` usage.
+
+2.  **Introduced `RpcBuilder` Class**:
+    - Encapsulates RPC parameters and execution logic.
+    - Adds `single()` method: Expects exactly one row. Throws `PGRST116` if 0 rows, `PGRST114` if >1 rows.
+    - Adds `maybeSingle()` method: Expects at most one row. Returns `null` if 0 rows, throws `PGRST114` if >1 rows.
+    - Preserves existing scalar unwrapping logic for single-row, single-column results.
+
+3.  **Unit Tests**:
+    - Added `src/__tests__/rpc.test.ts` covering various scenarios for standard calls, `.single()`, and `.maybeSingle()`.
+
+## Impact
+
+- Users can now use `.single()` on `rpc` calls, resolving the `TypeError: ...single is not a function` error.
+- Existing code using `await rpc(...)` continues to work without changes.

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