schematic-pg 0.1.19 → 0.1.20

package/README.md

@@ -390,6 +390,15 @@ functions {
     """
   }
 
+  function searchProducts(query: TEXT): TABLE(id: UUID, name: TEXT, price: DECIMAL) {
+    language: sql
+    volatility: STABLE
+    execute: """
+      SELECT id, name, price FROM product
+      WHERE name ILIKE '%' || query || '%'
+    """
+  }
+
   function setUpdatedAt(): TRIGGER {
     language: plpgsql
     execute: """
@@ -407,11 +416,11 @@ functions {
 | `security` | `INVOKER`, `DEFINER` | `INVOKER` |
 | `execute` | Triple-quoted SQL / PL/pgSQL | required |
 
-Return types are PostgreSQL types (`INTEGER`, `UUID`, `JSONB`, …), `TRIGGER`, or `VOID`. Body keys may be newline-separated or comma-separated.
+Return types are PostgreSQL types (`INTEGER`, `UUID`, `JSONB`, …), `TRIGGER`, `VOID`, or `TABLE(col: Type, …)` for set-returning functions. Body keys may be newline-separated or comma-separated. TABLE column names must be unique and must not collide with input parameter names.
 
 `language: plpgsql` wraps the body in `BEGIN` / `END` unless it already starts with `DECLARE` or `BEGIN`. Function names must be unique in the schema.
 
-`db:diff` treats body, language, volatility, and security changes as `CREATE OR REPLACE`. Argument or return-type changes drop the old function, then create the new one.
+`db:diff` treats body, language, volatility, and security changes as `CREATE OR REPLACE`. Argument or return-type changes (including TABLE column changes) drop the old function, then create the new one.
 
 Functions are database objects only in this release — they are not REST endpoints. Call them with `db.$queryRaw`:
 
@@ -420,6 +429,11 @@ const [row] = await db.$queryRaw<{ get_user_balance: number }>(
   'SELECT get_user_balance($1)',
   [userId],
 );
+
+const products = await db.$queryRaw<{ id: string; name: string; price: string }>(
+  'SELECT * FROM search_products($1)',
+  [query],
+);
 ```
 
 ---

package/dist/cli/templates/agents.md

@@ -100,7 +100,7 @@ models {
 - **Policies:** `@policy(role: ..., allow: [select|insert|update|delete|all], where: "...")` — `where` supports `{{auth.user.id}}`.
 - **Validation:** `@regex(...)`, `@range(min: ..., max: ...)` flow into generated Zod schemas.
 - **Indexes / triggers:** `@@index(...)`, `@@trigger { timing, event, level, execute: """...""" }`.
-- **SQL functions:** optional `functions { function name(args): ReturnType { execute: """...""" } }` after `models`. Names snake_case in SQL; call with `db.$queryRaw`.
+- **SQL functions:** optional `functions { function name(args): ReturnType { execute: """...""" } }` after `models`. `ReturnType` may be a scalar (`INTEGER`, `TRIGGER`, `VOID`, …) or `TABLE(col: Type, …)`. Names snake_case in SQL; call scalars with `SELECT fn($1)`, table functions with `SELECT * FROM fn($1)` via `db.$queryRaw`.
 
 ## Database Client
 

package/dist/schema-dsl/ast.d.ts

@@ -36,7 +36,7 @@ export interface SqlFunction {
     kind: 'SqlFunction';
     name: string;
     params: FunctionParam[];
-    returns: TypeExpr;
+    returns: FunctionReturn;
     language?: string;
     volatility?: string;
     security?: string;
@@ -49,6 +49,13 @@ export interface FunctionParam {
     type: TypeExpr;
     loc: SourceLocation;
 }
+export interface TableReturn {
+    kind: 'TableReturn';
+    columns: FunctionParam[];
+    loc: SourceLocation;
+}
+export type FunctionReturn = TypeExpr | TableReturn;
+export declare function isTableReturn(returns: FunctionReturn): returns is TableReturn;
 export interface Field {
     kind: 'Field';
     name: string;

package/dist/schema-dsl/ast.js

@@ -1 +1,3 @@
-export {};
+export function isTableReturn(returns) {
+    return returns.kind === 'TableReturn';
+}

package/dist/schema-dsl/parser.d.ts

@@ -22,6 +22,8 @@ export declare class Parser {
     private parseModelsSection;
     private parseFunctionsSection;
     parseFunction(existingNames?: Set<string>): SqlFunction;
+    private parseFunctionReturn;
+    private parseTableReturn;
     private parseFunctionParams;
     private parseFunctionParam;
     private parseFunctionBody;

package/dist/schema-dsl/parser.js

@@ -137,7 +137,7 @@ export class Parser {
         const params = this.parseFunctionParams();
         this.expect(TokenType.RPAREN, "')'");
         this.expect(TokenType.COLON, "':'");
-        const returns = this.parseTypeExpr();
+        const returns = this.parseFunctionReturn(params);
         this.expect(TokenType.LBRACE, "'{'");
         const body = this.parseFunctionBody();
         this.expect(TokenType.RBRACE, "'}'");
@@ -153,6 +153,53 @@ export class Parser {
             loc: this.loc(start),
         };
     }
+    parseFunctionReturn(params) {
+        const current = this.current();
+        if (current.type === TokenType.IDENT &&
+            current.value === 'TABLE' &&
+            this.peekType(1) === TokenType.LPAREN) {
+            return this.parseTableReturn(params);
+        }
+        if (current.type === TokenType.IDENT && current.value === 'TABLE') {
+            throw new ParseError("TABLE column list '(...)'", current);
+        }
+        return this.parseTypeExpr();
+    }
+    parseTableReturn(params) {
+        const start = this.expect(TokenType.IDENT, "'TABLE'");
+        this.expect(TokenType.LPAREN, "'('");
+        if (this.check(TokenType.RPAREN)) {
+            throw new ParseError('at least one TABLE column', this.current());
+        }
+        const columns = [];
+        const columnNames = new Set();
+        const paramNames = new Set(params.map((param) => param.name));
+        do {
+            const nameToken = this.expect(TokenType.IDENT, 'TABLE column name');
+            if (columnNames.has(nameToken.value)) {
+                throw new ParseError(`unique TABLE column name, "${nameToken.value}" already defined`, nameToken);
+            }
+            if (paramNames.has(nameToken.value)) {
+                throw new ParseError(`TABLE column name distinct from parameter "${nameToken.value}"`, nameToken);
+            }
+            columnNames.add(nameToken.value);
+            this.expect(TokenType.COLON, "':'");
+            const type = this.parseTypeExpr();
+            columns.push({
+                kind: 'FunctionParam',
+                name: nameToken.value,
+                type,
+                loc: this.loc(nameToken),
+            });
+        } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
+        this.consumeTrailingComma();
+        this.expect(TokenType.RPAREN, "')'");
+        return {
+            kind: 'TableReturn',
+            columns,
+            loc: this.loc(start),
+        };
+    }
     parseFunctionParams() {
         if (this.check(TokenType.RPAREN)) {
             return [];

package/dist/sql-generator/generators/functions.js

@@ -1,4 +1,4 @@
-import { getEnumNames, normalizeFunction, } from '../utils/ast-helpers.js';
+import { formatNormalizedFunctionReturn, getEnumNames, normalizeFunction, } from '../utils/ast-helpers.js';
 import { joinSection } from '../utils/format.js';
 import { quoteIdentifier } from '../utils/snake-case.js';
 export function generateCreateFunction(normalized) {
@@ -8,7 +8,7 @@ export function generateCreateFunction(normalized) {
         .join(', ');
     const clauses = [
         `CREATE OR REPLACE FUNCTION ${functionName}(${params})`,
-        `RETURNS ${normalized.returns}`,
+        `RETURNS ${formatNormalizedFunctionReturn(normalized.returns)}`,
         `LANGUAGE ${normalized.language}`,
     ];
     if (normalized.volatility !== 'VOLATILE') {

package/dist/sql-generator/utils/ast-helpers.d.ts

@@ -61,16 +61,24 @@ export interface NormalizedFunctionParam {
     sqlName: string;
     sqlType: string;
 }
+export type NormalizedFunctionReturn = {
+    kind: 'scalar';
+    sqlType: string;
+} | {
+    kind: 'table';
+    columns: NormalizedFunctionParam[];
+};
 export interface NormalizedFunction {
     name: string;
     sqlName: string;
     params: NormalizedFunctionParam[];
-    returns: string;
+    returns: NormalizedFunctionReturn;
     language: string;
     volatility: string;
     security: string;
     execute: string;
 }
 export declare function normalizeFunction(sqlFunction: SqlFunction, enumNames: Set<string>): NormalizedFunction;
+export declare function formatNormalizedFunctionReturn(returns: NormalizedFunctionReturn): string;
 export declare function functionIdentity(normalized: NormalizedFunction): string;
 export declare function functionSignature(normalized: NormalizedFunction): string;

package/dist/sql-generator/utils/ast-helpers.js

@@ -1,6 +1,7 @@
+import { isTableReturn } from '../../schema-dsl/ast.js';
 import { formatDefaultValue, serializeValue } from './value-formatter.js';
 import { mapColumnType } from './type-mapper.js';
-import { toSnakeCase, toTableName } from './snake-case.js';
+import { toSnakeCase, toTableName, quoteIdentifier } from './snake-case.js';
 export function getModelNames(schema) {
     return new Set(schema.models.map((model) => model.name));
 }
@@ -251,21 +252,44 @@ export function resolveTriggerNames(model, timing, event) {
     };
 }
 export function normalizeFunction(sqlFunction, enumNames) {
+    const params = sqlFunction.params.map((param) => ({
+        name: param.name,
+        sqlName: toSnakeCase(param.name),
+        sqlType: serializeColumnType(param.type, enumNames),
+    }));
+    const returns = isTableReturn(sqlFunction.returns)
+        ? {
+            kind: 'table',
+            columns: sqlFunction.returns.columns.map((column) => ({
+                name: column.name,
+                sqlName: toSnakeCase(column.name),
+                sqlType: serializeColumnType(column.type, enumNames),
+            })),
+        }
+        : {
+            kind: 'scalar',
+            sqlType: serializeColumnType(sqlFunction.returns, enumNames),
+        };
     return {
         name: sqlFunction.name,
         sqlName: toSnakeCase(sqlFunction.name),
-        params: sqlFunction.params.map((param) => ({
-            name: param.name,
-            sqlName: toSnakeCase(param.name),
-            sqlType: serializeColumnType(param.type, enumNames),
-        })),
-        returns: serializeColumnType(sqlFunction.returns, enumNames),
+        params,
+        returns,
         language: (sqlFunction.language ?? 'sql').toLowerCase(),
         volatility: (sqlFunction.volatility ?? 'VOLATILE').toUpperCase(),
         security: (sqlFunction.security ?? 'INVOKER').toUpperCase(),
         execute: sqlFunction.execute.trim(),
     };
 }
+export function formatNormalizedFunctionReturn(returns) {
+    if (returns.kind === 'scalar') {
+        return returns.sqlType;
+    }
+    const columns = returns.columns
+        .map((column) => `${quoteIdentifier(column.sqlName)} ${column.sqlType}`)
+        .join(', ');
+    return `TABLE (${columns})`;
+}
 export function functionIdentity(normalized) {
     return JSON.stringify({
         sqlName: normalized.sqlName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematic-pg",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Single-file backend framework for PostgreSQL and Node.js",
   "type": "module",
   "license": "MIT",