Merge pull request #273 from constructive-io/devin/1767756786-auto-return-info

feat(plpgsql-parser): automatically compute return info for correct RETURN handling

Author: pyramation

packages/plpgsql-deparser/README.md

@@ -16,9 +16,11 @@ PL/pgSQL AST Deparser - Converts PL/pgSQL function ASTs back to SQL strings.
 
 > **⚠️ Experimental:** This package is currently experimental. If you're looking for SQL deparsing (not PL/pgSQL), see [`pgsql-deparser`](https://www.npmjs.com/package/pgsql-deparser).
 
+> **For full SQL + PL/pgSQL deparsing:** If you need to deparse complete `CREATE FUNCTION` statements (not just function bodies), use [`plpgsql-parser`](https://www.npmjs.com/package/plpgsql-parser) instead. It handles the full heterogeneous parsing/deparsing pipeline automatically.
+
 ## Overview
 
-This package provides a deparser for PL/pgSQL (PostgreSQL's procedural language) AST structures. It works with the AST output from `parsePlPgSQL` function in `@libpg-query/parser`.
+This package provides a **body-only** deparser for PL/pgSQL (PostgreSQL's procedural language) AST structures. It converts PL/pgSQL function bodies (the `BEGIN...END` part) back to strings. It works with the AST output from `parsePlPgSQL` function in `@libpg-query/parser`.
 
 The PL/pgSQL AST is different from the regular SQL AST - it represents the internal structure of PL/pgSQL function bodies, including:
 
@@ -177,13 +179,32 @@ interface PLpgSQLDeparserOptions {
 
 ## Note on AST Structure
 
-The PL/pgSQL AST returned by `parsePlPgSQL` represents the internal structure of function bodies, not the `CREATE FUNCTION` statement itself. To get a complete function definition, you would need to:
+This package deparses **only the function body** (the `BEGIN...END` part), not the full `CREATE FUNCTION` statement.
+
+For full SQL + PL/pgSQL deparsing, use [`plpgsql-parser`](https://www.npmjs.com/package/plpgsql-parser):
+
+```typescript
+import { parse, deparseSync, loadModule } from 'plpgsql-parser';
+
+await loadModule();
+
+const parsed = parse(`
+  CREATE FUNCTION my_func() RETURNS void LANGUAGE plpgsql AS $$
+  BEGIN
+    RAISE NOTICE 'Hello';
+  END;
+  $$;
+`);
+
+// Full round-trip: parses SQL + PL/pgSQL, deparses back to complete SQL
+const sql = deparseSync(parsed);
+```
 
-1. Parse the `CREATE FUNCTION` statement with the regular `parse()` function
-2. Extract the function body
-3. Parse the body with `parsePlPgSQL()`
-4. Deparse the body with this package
-5. Combine with the outer `CREATE FUNCTION` statement
+The `plpgsql-parser` package handles:
+- Parsing the outer `CREATE FUNCTION` statement
+- Hydrating embedded SQL expressions in the PL/pgSQL body
+- Correct `RETURN` statement handling based on function return type
+- Stitching the deparsed body back into the full SQL
 
 ## License
 

packages/plpgsql-parser/README.md

@@ -14,16 +14,22 @@
 
 Combined SQL + PL/pgSQL parser with hydrated ASTs and transform API.
 
-> **⚠️ Experimental:** This package is currently experimental. If you're looking for just SQL parsing, see [`pgsql-parser`](https://www.npmjs.com/package/pgsql-parser). For just PL/pgSQL deparsing, see [`plpgsql-deparser`](https://www.npmjs.com/package/plpgsql-deparser).
+> **⚠️ Experimental:** This package is currently experimental. If you're looking for just SQL parsing, see [`pgsql-parser`](https://www.npmjs.com/package/pgsql-parser). For body-only PL/pgSQL deparsing, see [`plpgsql-deparser`](https://www.npmjs.com/package/plpgsql-deparser).
 
 ## Overview
 
-This package provides a unified API for parsing SQL scripts containing PL/pgSQL functions. It combines the SQL parser and PL/pgSQL parser, automatically detecting and hydrating PL/pgSQL function bodies.
+This package provides a unified API for **heterogeneous parsing and deparsing** of SQL scripts containing PL/pgSQL functions. It handles the full pipeline: parsing SQL + PL/pgSQL together, transforming ASTs, and deparsing back to complete SQL.
+
+**Use this package when you need to:**
+- Parse and deparse complete `CREATE FUNCTION` statements with PL/pgSQL bodies
+- Transform both SQL and embedded PL/pgSQL expressions (e.g., rename schemas)
+- Round-trip SQL through parse → modify → deparse
 
 Key features:
 
 - Auto-detects `CREATE FUNCTION` statements with `LANGUAGE plpgsql`
 - Hydrates PL/pgSQL function bodies into structured ASTs
+- Automatic `RETURN` statement handling based on function return type
 - Transform API for parse → modify → deparse workflows
 - Re-exports underlying primitives for power users
 

packages/plpgsql-parser/__tests__/plpgsql-parser.test.ts

@@ -111,4 +111,102 @@ describe('plpgsql-parser', () => {
       expect(result).toContain('\n');
     });
   });
+
+  describe('automatic return info handling', () => {
+    it('should preserve bare RETURN for SETOF functions', () => {
+      const setofSql = `
+        CREATE FUNCTION get_users()
+        RETURNS SETOF users
+        LANGUAGE plpgsql AS $$
+        BEGIN
+          RETURN QUERY SELECT * FROM users;
+          RETURN;
+        END;
+        $$;
+      `;
+      
+      const parsed = parse(setofSql);
+      const result = deparseSync(parsed);
+      
+      // SETOF functions should keep bare RETURN (not RETURN NULL)
+      expect(result).toMatch(/RETURN\s*;/);
+      expect(result).not.toMatch(/RETURN\s+NULL\s*;/);
+    });
+
+    it('should emit RETURN NULL for scalar functions with empty return', () => {
+      const scalarSql = `
+        CREATE FUNCTION get_value()
+        RETURNS int
+        LANGUAGE plpgsql AS $$
+        BEGIN
+          RETURN;
+        END;
+        $$;
+      `;
+      
+      const parsed = parse(scalarSql);
+      const result = deparseSync(parsed);
+      
+      // Scalar functions with empty RETURN should become RETURN NULL
+      expect(result).toMatch(/RETURN\s+NULL\s*;/);
+    });
+
+    it('should preserve bare RETURN for void functions', () => {
+      const voidSql = `
+        CREATE FUNCTION do_something()
+        RETURNS void
+        LANGUAGE plpgsql AS $$
+        BEGIN
+          RAISE NOTICE 'done';
+          RETURN;
+        END;
+        $$;
+      `;
+      
+      const parsed = parse(voidSql);
+      const result = deparseSync(parsed);
+      
+      // Void functions should keep bare RETURN
+      expect(result).toMatch(/RETURN\s*;/);
+      expect(result).not.toMatch(/RETURN\s+NULL\s*;/);
+    });
+
+    it('should preserve bare RETURN for trigger functions', () => {
+      const triggerSql = `
+        CREATE FUNCTION my_trigger()
+        RETURNS trigger
+        LANGUAGE plpgsql AS $$
+        BEGIN
+          RETURN NEW;
+        END;
+        $$;
+      `;
+      
+      const parsed = parse(triggerSql);
+      const result = deparseSync(parsed);
+      
+      // Trigger functions should work correctly (case-insensitive check)
+      expect(result.toLowerCase()).toContain('return new');
+    });
+
+    it('should preserve bare RETURN for OUT parameter functions', () => {
+      const outParamSql = `
+        CREATE FUNCTION get_info(OUT result text)
+        RETURNS text
+        LANGUAGE plpgsql AS $$
+        BEGIN
+          result := 'hello';
+          RETURN;
+        END;
+        $$;
+      `;
+      
+      const parsed = parse(outParamSql);
+      const result = deparseSync(parsed);
+      
+      // OUT parameter functions should keep bare RETURN
+      expect(result).toMatch(/RETURN\s*;/);
+      expect(result).not.toMatch(/RETURN\s+NULL\s*;/);
+    });
+  });
 });