plpgsql-parse 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Dan Lynch <pyramation@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# plpgsql-parse
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+Comment preserving PL/pgSQL parser. A wrapper around `plpgsql-parser` and `plpgsql-deparser` that preserves `--` line comments inside PL/pgSQL function bodies through parse-deparse round trips.
+
+## Installation
+
+```sh
+npm install plpgsql-parse
+```
+
+## Features
+
+* **Body Comment Preservation** -- Retains `--` line comments inside PL/pgSQL function bodies (`$$...$$`) through parse-deparse cycles
+* **Outer SQL Comment Preservation** -- Preserves comments and whitespace outside function definitions via `pgsql-parse`
+* **Idempotent Round-Trips** -- `parse -> deparse -> parse -> deparse` produces identical output
+* **Non-Invasive** -- Does not modify `plpgsql-parser`, `plpgsql-deparser`, or any other upstream packages
+
+## How It Works
+
+1. Uses `pgsql-parse` for outer SQL comment and whitespace preservation
+2. For each PL/pgSQL function, scans the `$$...$$` body to extract `--` comments with line numbers
+3. Associates each comment with the nearest following PL/pgSQL statement (anchor)
+4. On deparse, re-injects comments by matching statement keywords against the deparsed output
+
+## API
+
+### Parse
+
+```typescript
+import { parseSync, deparseSync, loadModule } from 'plpgsql-parse';
+
+await loadModule();
+
+const result = parseSync(`
+-- Create a counter function
+CREATE FUNCTION get_count() RETURNS int LANGUAGE plpgsql AS $$
+BEGIN
+  -- Count active users
+  RETURN (SELECT count(*) FROM users WHERE active);
+END;
+$$;
+`);
+
+// result.enhanced contains outer SQL comments/whitespace
+// result.functions contains body comments for each PL/pgSQL function
+const sql = deparseSync(result);
+// Output preserves both outer and body comments
+```
+
+## Credits
+
+Built on the excellent work of several contributors:
+
+* **[Dan Lynch](https://github.com/pyramation)** -- official maintainer since 2018 and architect of the current implementation
+* **[Lukas Fittl](https://github.com/lfittl)** for [libpg_query](https://github.com/pganalyze/libpg_query) -- the core PostgreSQL parser that powers this project
+
+---
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Related
+
+* [pgpm](https://pgpm.dev): A Postgres Package Manager that brings modular development to PostgreSQL with reusable packages, deterministic migrations, recursive dependency resolution, and tag-aware versioning.
+* [pgsql-test](https://www.npmjs.com/package/pgsql-test): Instant, isolated PostgreSQL databases for each test with automatic transaction rollbacks, context switching, and clean seeding for fast, reliable database testing.
+* [pgsql-seed](https://www.npmjs.com/package/pgsql-seed): PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
+* [pgsql-deparser](https://www.npmjs.com/package/pgsql-deparser): A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement `pgsql-parser`.
+* [@pgsql/parser](https://www.npmjs.com/package/@pgsql/parser): Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): A comprehensive utility library for PostgreSQL, offering type-safe AST node creation and enum value conversions, simplifying the construction and manipulation of PostgreSQL ASTs.
+* [@pgsql/traverse](https://www.npmjs.com/package/@pgsql/traverse): PostgreSQL AST traversal utilities for pgsql-parser, providing a visitor pattern for traversing PostgreSQL Abstract Syntax Tree nodes, similar to Babel's traverse functionality but specifically designed for PostgreSQL AST structures.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [libpg-query](https://github.com/constructive-io/libpg-query-node): The real PostgreSQL parser exposed for Node.js, used primarily in `pgsql-parser` for parsing and deparsing SQL queries.
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating Software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Software code or Software CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/body-scanner.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Scanner for extracting comments from PL/pgSQL function bodies.
+ *
+ * Uses simple line-based scanning since the body text has already been
+ * extracted from the dollar-quoted string — no need to worry about
+ * string literal boundaries at this level.
+ */
+import type { BodyComment } from './types';
+/**
+ * Scan a PL/pgSQL function body for -- line comments.
+ *
+ * Returns an array of BodyComment objects ordered by line number.
+ * Only detects standalone comment lines (lines where the first
+ * non-whitespace content is --). Inline trailing comments on code
+ * lines are not extracted since the PL/pgSQL deparser cannot
+ * reconstruct them at the right position.
+ */
+export declare function scanBodyComments(body: string): BodyComment[];
+/**
+ * A comment group: one or more consecutive comment lines
+ * associated with the code that follows them.
+ */
+export interface CommentGroup {
+    /** The comment lines (trimmed, with -- prefix) */
+    comments: string[];
+    /**
+     * The lineno of the PL/pgSQL statement this group precedes.
+     * null if the comments are at the end of the body (after all statements).
+     */
+    anchorLineno: number | null;
+}
+/**
+ * Associate body comments with PL/pgSQL statement line numbers.
+ *
+ * For each comment, finds the first statement whose lineno is greater
+ * than the comment's line number. Groups consecutive comments together.
+ *
+ * @param comments - Comments extracted by scanBodyComments
+ * @param stmtLinenos - Sorted array of statement lineno values from the PL/pgSQL AST
+ */
+export declare function groupCommentsByAnchor(comments: BodyComment[], stmtLinenos: number[]): CommentGroup[];

package/body-scanner.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Scanner for extracting comments from PL/pgSQL function bodies.
+ *
+ * Uses simple line-based scanning since the body text has already been
+ * extracted from the dollar-quoted string — no need to worry about
+ * string literal boundaries at this level.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanBodyComments = scanBodyComments;
+exports.groupCommentsByAnchor = groupCommentsByAnchor;
+/**
+ * Scan a PL/pgSQL function body for -- line comments.
+ *
+ * Returns an array of BodyComment objects ordered by line number.
+ * Only detects standalone comment lines (lines where the first
+ * non-whitespace content is --). Inline trailing comments on code
+ * lines are not extracted since the PL/pgSQL deparser cannot
+ * reconstruct them at the right position.
+ */
+function scanBodyComments(body) {
+    const lines = body.split('\n');
+    const comments = [];
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith('--')) {
+            comments.push({
+                text: trimmed,
+                lineNo: i + 1, // 1-based
+                standalone: true,
+            });
+        }
+    }
+    return comments;
+}
+/**
+ * Associate body comments with PL/pgSQL statement line numbers.
+ *
+ * For each comment, finds the first statement whose lineno is greater
+ * than the comment's line number. Groups consecutive comments together.
+ *
+ * @param comments - Comments extracted by scanBodyComments
+ * @param stmtLinenos - Sorted array of statement lineno values from the PL/pgSQL AST
+ */
+function groupCommentsByAnchor(comments, stmtLinenos) {
+    if (comments.length === 0)
+        return [];
+    const groups = [];
+    let currentGroup = [];
+    let lastLineNo = -1;
+    for (const comment of comments) {
+        // Start a new group if there's a gap (non-consecutive lines)
+        if (lastLineNo >= 0 && comment.lineNo > lastLineNo + 1) {
+            if (currentGroup.length > 0) {
+                const anchor = findAnchorLineno(lastLineNo, stmtLinenos);
+                groups.push({ comments: [...currentGroup], anchorLineno: anchor });
+                currentGroup = [];
+            }
+        }
+        currentGroup.push(comment.text);
+        lastLineNo = comment.lineNo;
+    }
+    // Flush remaining group
+    if (currentGroup.length > 0) {
+        const anchor = findAnchorLineno(lastLineNo, stmtLinenos);
+        groups.push({ comments: [...currentGroup], anchorLineno: anchor });
+    }
+    return groups;
+}
+/**
+ * Find the first statement lineno that comes after the given line number.
+ */
+function findAnchorLineno(afterLine, stmtLinenos) {
+    for (const lineno of stmtLinenos) {
+        if (lineno > afterLine) {
+            return lineno;
+        }
+    }
+    return null;
+}

package/deparse.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Enhanced deparse that re-injects body comments into PL/pgSQL function
+ * bodies after the standard plpgsql-deparser has produced its output.
+ *
+ * Also handles outer SQL comments/whitespace via pgsql-parse's deparser.
+ *
+ * This module does NOT modify plpgsql-deparser or pgsql-deparser.
+ */
+import type { PlpgsqlParseResult } from './types';
+export interface DeparseOptions {
+    pretty?: boolean;
+    newline?: string;
+}
+/**
+ * Deparse a PlpgsqlParseResult back to SQL, preserving both outer
+ * comments/whitespace AND comments inside PL/pgSQL function bodies.
+ */
+export declare function deparseSync(result: PlpgsqlParseResult, options?: DeparseOptions): string;
+/**
+ * Async version of deparseSync.
+ */
+export declare function deparse(result: PlpgsqlParseResult, options?: DeparseOptions): Promise<string>;