pgsql-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,107 @@
+# pgsql-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 and whitespace preserving PostgreSQL parser. A drop-in enhancement for `pgsql-parser` that preserves SQL comments (`--` line and `/* */` block) and vertical whitespace (blank lines) through parse-deparse round trips.
+
+## Installation
+
+```sh
+npm install pgsql-parse
+```
+
+## Features
+
+* **Comment Preservation** -- Retains `--` line comments and `/* */` block comments through parse-deparse cycles
+* **Vertical Whitespace** -- Preserves blank lines between statements for readable output
+* **Idempotent Round-Trips** -- `parse -> deparse -> parse -> deparse` produces identical output
+* **Drop-in API** -- Re-exports `parse`, `parseSync`, `deparse`, `deparseSync`, `loadModule` from `pgsql-parser`
+* **Synthetic AST Nodes** -- `RawComment` and `RawWhitespace` nodes interleaved into the `stmts` array by byte position
+
+## How It Works
+
+1. A pure TypeScript scanner extracts comment and whitespace tokens with byte positions from the raw SQL text
+2. Enhanced `parse`/`parseSync` call the standard `libpg-query` parser, then interleave synthetic `RawComment` and `RawWhitespace` nodes into the `stmts` array based on byte position
+3. `deparseEnhanced()` dispatches on node type -- real `RawStmt` entries go through the standard deparser, while synthetic nodes emit their comment text or blank lines directly
+
+## API
+
+### Enhanced Parse
+
+```typescript
+import { parse, parseSync, deparseEnhanced, loadModule } from 'pgsql-parse';
+
+// Async (handles initialization automatically)
+const result = await parse(`
+-- Create users table
+CREATE TABLE users (id serial PRIMARY KEY);
+
+-- Create posts table
+CREATE TABLE posts (id serial PRIMARY KEY);
+`);
+
+// result.stmts contains RawComment, RawWhitespace, and RawStmt nodes
+const sql = deparseEnhanced(result);
+// Output preserves comments and blank lines
+```
+
+### Sync Methods
+
+```typescript
+import { parseSync, deparseEnhanced, loadModule } from 'pgsql-parse';
+
+await loadModule();
+
+const result = parseSync('-- comment\nSELECT 1;');
+const sql = deparseEnhanced(result);
+```
+
+### Type Guards
+
+```typescript
+import { isRawComment, isRawWhitespace, isRawStmt } from 'pgsql-parse';
+
+for (const stmt of result.stmts) {
+  if (isRawComment(stmt)) {
+    console.log('Comment:', stmt.RawComment.text);
+  } else if (isRawWhitespace(stmt)) {
+    console.log('Blank lines:', stmt.RawWhitespace.lines);
+  } else if (isRawStmt(stmt)) {
+    console.log('Statement:', stmt);
+  }
+}
+```
+
+## 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/deparse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Enhanced deparser that handles synthetic RawComment and RawWhitespace nodes
+ * in addition to all standard PostgreSQL AST nodes.
+ *
+ * This does NOT modify the upstream Deparser class. Instead, it processes
+ * the EnhancedParseResult's stmts array and delegates real statements
+ * to the standard deparser.
+ */
+import { Deparser, DeparserOptions } from 'pgsql-deparser';
+import { EnhancedParseResult } from './types';
+/**
+ * Deparse an EnhancedParseResult back to SQL, preserving comments
+ * and vertical whitespace.
+ *
+ * The output strategy:
+ * - Each real statement gets a newline separator from the previous element
+ * - RawComment nodes emit their comment text
+ * - RawWhitespace nodes emit blank lines (the node itself IS the separator)
+ * - Adjacent statements/comments without a RawWhitespace between them
+ *   get a single newline separator
+ */
+export declare function deparseEnhanced(result: EnhancedParseResult, opts?: DeparserOptions): string;
+/**
+ * Sync version of deparseEnhanced.
+ */
+export declare const deparseEnhancedSync: typeof deparseEnhanced;
+/**
+ * Standard deparse — re-exported from pgsql-deparser for convenience.
+ * Use this when you have a standard ParseResult without synthetic nodes.
+ */
+export { Deparser, DeparserOptions };

package/deparse.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Enhanced deparser that handles synthetic RawComment and RawWhitespace nodes
+ * in addition to all standard PostgreSQL AST nodes.
+ *
+ * This does NOT modify the upstream Deparser class. Instead, it processes
+ * the EnhancedParseResult's stmts array and delegates real statements
+ * to the standard deparser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Deparser = exports.deparseEnhancedSync = void 0;
+exports.deparseEnhanced = deparseEnhanced;
+const pgsql_deparser_1 = require("pgsql-deparser");
+Object.defineProperty(exports, "Deparser", { enumerable: true, get: function () { return pgsql_deparser_1.Deparser; } });
+const types_1 = require("./types");
+/**
+ * Deparse a single RawComment node back to SQL comment text.
+ */
+function deparseComment(comment) {
+    return `--${comment.text}`;
+}
+/**
+ * Deparse an EnhancedParseResult back to SQL, preserving comments
+ * and vertical whitespace.
+ *
+ * The output strategy:
+ * - Each real statement gets a newline separator from the previous element
+ * - RawComment nodes emit their comment text
+ * - RawWhitespace nodes emit blank lines (the node itself IS the separator)
+ * - Adjacent statements/comments without a RawWhitespace between them
+ *   get a single newline separator
+ */
+function deparseEnhanced(result, opts = {}) {
+    const newline = opts.newline ?? '\n';
+    const lines = [];
+    for (const stmt of result.stmts) {
+        if ((0, types_1.isRawComment)(stmt)) {
+            const commentText = deparseComment(stmt.RawComment);
+            if (stmt.RawComment.trailing && lines.length > 0) {
+                // Trailing comment: append to the previous line
+                lines[lines.length - 1] += ' ' + commentText;
+            }
+            else {
+                lines.push(commentText);
+            }
+        }
+        else if ((0, types_1.isRawWhitespace)(stmt)) {
+            // Each blank line in the original source becomes an empty line in output.
+            // The whitespace node represents N blank lines between content.
+            for (let i = 0; i < stmt.RawWhitespace.lines; i++) {
+                lines.push('');
+            }
+        }
+        else if ((0, types_1.isRawStmt)(stmt)) {
+            // Wrap in a minimal ParseResult so the standard deparser handles it
+            const sql = pgsql_deparser_1.Deparser.deparse({ version: 0, stmts: [stmt] }, opts);
+            if (sql) {
+                lines.push(sql);
+            }
+        }
+    }
+    return lines.join(newline);
+}
+/**
+ * Sync version of deparseEnhanced.
+ */
+exports.deparseEnhancedSync = deparseEnhanced;

package/esm/deparse.js

@@ -0,0 +1,67 @@
+/**
+ * Enhanced deparser that handles synthetic RawComment and RawWhitespace nodes
+ * in addition to all standard PostgreSQL AST nodes.
+ *
+ * This does NOT modify the upstream Deparser class. Instead, it processes
+ * the EnhancedParseResult's stmts array and delegates real statements
+ * to the standard deparser.
+ */
+import { Deparser } from 'pgsql-deparser';
+import { isRawComment, isRawWhitespace, isRawStmt, } from './types';
+/**
+ * Deparse a single RawComment node back to SQL comment text.
+ */
+function deparseComment(comment) {
+    return `--${comment.text}`;
+}
+/**
+ * Deparse an EnhancedParseResult back to SQL, preserving comments
+ * and vertical whitespace.
+ *
+ * The output strategy:
+ * - Each real statement gets a newline separator from the previous element
+ * - RawComment nodes emit their comment text
+ * - RawWhitespace nodes emit blank lines (the node itself IS the separator)
+ * - Adjacent statements/comments without a RawWhitespace between them
+ *   get a single newline separator
+ */
+export function deparseEnhanced(result, opts = {}) {
+    const newline = opts.newline ?? '\n';
+    const lines = [];
+    for (const stmt of result.stmts) {
+        if (isRawComment(stmt)) {
+            const commentText = deparseComment(stmt.RawComment);
+            if (stmt.RawComment.trailing && lines.length > 0) {
+                // Trailing comment: append to the previous line
+                lines[lines.length - 1] += ' ' + commentText;
+            }
+            else {
+                lines.push(commentText);
+            }
+        }
+        else if (isRawWhitespace(stmt)) {
+            // Each blank line in the original source becomes an empty line in output.
+            // The whitespace node represents N blank lines between content.
+            for (let i = 0; i < stmt.RawWhitespace.lines; i++) {
+                lines.push('');
+            }
+        }
+        else if (isRawStmt(stmt)) {
+            // Wrap in a minimal ParseResult so the standard deparser handles it
+            const sql = Deparser.deparse({ version: 0, stmts: [stmt] }, opts);
+            if (sql) {
+                lines.push(sql);
+            }
+        }
+    }
+    return lines.join(newline);
+}
+/**
+ * Sync version of deparseEnhanced.
+ */
+export const deparseEnhancedSync = deparseEnhanced;
+/**
+ * Standard deparse — re-exported from pgsql-deparser for convenience.
+ * Use this when you have a standard ParseResult without synthetic nodes.
+ */
+export { Deparser };

package/esm/index.js

@@ -0,0 +1,26 @@
+/**
+ * pgsql-parse — Comment and whitespace preserving PostgreSQL parser.
+ *
+ * Drop-in enhancement over pgsql-parser that preserves SQL -- line
+ * comments and vertical whitespace (blank lines) through
+ * parse→deparse round trips.
+ *
+ * Synthetic AST nodes:
+ * - RawComment: represents a SQL comment
+ * - RawWhitespace: represents significant vertical whitespace
+ *
+ * These nodes are interleaved with real RawStmt entries in the
+ * stmts array, ordered by byte position in the original source.
+ */
+// Enhanced parse functions (comment/whitespace preserving)
+export { parse, parseSync } from './parse';
+// Enhanced deparse function
+export { deparseEnhanced, deparseEnhancedSync, Deparser } from './deparse';
+// Re-export standard deparse for non-enhanced use
+export { deparse, deparseSync } from 'pgsql-deparser';
+// Re-export loadModule from @libpg-query/parser
+export { loadModule } from '@libpg-query/parser';
+// Types
+export { isRawComment, isRawWhitespace, isRawStmt, } from './types';
+// Scanner (for advanced use)
+export { scanComments } from './scanner';

package/esm/parse.js

@@ -0,0 +1,134 @@
+/**
+ * Enhanced parse functions that preserve comments and vertical whitespace
+ * by interleaving synthetic RawComment and RawWhitespace nodes into the
+ * parse result's stmts array.
+ */
+import { parse as libParse, parseSync as libParseSync } from '@libpg-query/parser';
+import { scanComments } from './scanner';
+/**
+ * Find the actual SQL start position for a statement by skipping
+ * past any comments and whitespace that the parser included in
+ * the stmt_location..stmt_location+stmt_len range.
+ *
+ * The parser's stmt_location often includes preceding whitespace
+ * and comments that were stripped during parsing. We need the
+ * position of the first real SQL token.
+ */
+function findActualSqlStart(sql, stmtLoc, elements) {
+    let pos = stmtLoc;
+    // Iteratively skip whitespace and any scanned elements (comments/whitespace)
+    // that start at or after our current position
+    let changed = true;
+    while (changed) {
+        changed = false;
+        // Skip whitespace characters
+        while (pos < sql.length && /\s/.test(sql[pos])) {
+            pos++;
+            changed = true;
+        }
+        // Skip past any scanned element that starts at current position
+        for (const elem of elements) {
+            if (elem.value.start === pos || (elem.value.start >= stmtLoc && elem.value.start < pos + 1 && elem.value.end > pos)) {
+                if (elem.value.end > pos) {
+                    pos = elem.value.end;
+                    changed = true;
+                }
+            }
+        }
+    }
+    return pos;
+}
+function buildStmtRanges(stmts, sql, elements) {
+    return stmts.map(stmt => {
+        const loc = stmt.stmt_location ?? 0;
+        const actualStart = findActualSqlStart(sql, loc, elements);
+        const len = stmt.stmt_len ?? sql.length - loc;
+        return { actualStart, end: loc + len };
+    });
+}
+function interleave(parseResult, sql, elements) {
+    const stmts = parseResult.stmts ?? [];
+    const items = [];
+    const ranges = buildStmtRanges(stmts, sql, elements);
+    // Add scanned elements (comments and whitespace)
+    for (const elem of elements) {
+        if (elem.kind === 'comment') {
+            // Check if this comment falls inside a statement's byte range.
+            // If so, hoist it above that statement instead of leaving it
+            // at its original position (which would place it after the
+            // statement or trailing at the wrong spot).
+            let hoistedPosition = null;
+            for (const range of ranges) {
+                if (elem.value.start > range.actualStart && elem.value.start < range.end) {
+                    hoistedPosition = range.actualStart;
+                    break;
+                }
+            }
+            items.push({
+                position: hoistedPosition ?? elem.value.start,
+                priority: 0,
+                entry: {
+                    RawComment: {
+                        type: elem.value.type,
+                        text: elem.value.text,
+                        location: elem.value.start,
+                        // Only preserve trailing flag when NOT hoisted —
+                        // a hoisted comment becomes a standalone line above the statement.
+                        ...(hoistedPosition == null && elem.value.trailing ? { trailing: true } : {}),
+                    }
+                }
+            });
+        }
+        else {
+            items.push({
+                position: elem.value.start,
+                priority: 1, // whitespace sorts after comments at same position
+                entry: {
+                    RawWhitespace: {
+                        lines: elem.value.lines,
+                        location: elem.value.start,
+                    }
+                }
+            });
+        }
+    }
+    // Add parsed statements with their actual SQL start position
+    for (let i = 0; i < stmts.length; i++) {
+        items.push({
+            position: ranges[i].actualStart,
+            priority: 2, // statements sort after comments and whitespace
+            entry: stmts[i],
+        });
+    }
+    // Sort by position, then by priority
+    items.sort((a, b) => {
+        if (a.position !== b.position)
+            return a.position - b.position;
+        return a.priority - b.priority;
+    });
+    return {
+        version: parseResult.version,
+        stmts: items.map(item => item.entry),
+    };
+}
+/**
+ * Parse SQL with comment and whitespace preservation (async).
+ *
+ * Returns an EnhancedParseResult where the stmts array contains
+ * real RawStmt entries interleaved with synthetic RawComment and
+ * RawWhitespace nodes, all ordered by their byte position in the
+ * original source text.
+ */
+export async function parse(sql) {
+    const parseResult = await libParse(sql);
+    const elements = scanComments(sql);
+    return interleave(parseResult, sql, elements);
+}
+/**
+ * Parse SQL with comment and whitespace preservation (sync).
+ */
+export function parseSync(sql) {
+    const parseResult = libParseSync(sql);
+    const elements = scanComments(sql);
+    return interleave(parseResult, sql, elements);
+}

package/esm/scanner.js

@@ -0,0 +1,94 @@
+/**
+ * Scanner for extracting comments and vertical whitespace
+ * from PostgreSQL SQL source text.
+ *
+ * Uses PostgreSQL's real lexer via @libpg-query/parser's scanSync()
+ * to identify SQL_COMMENT tokens with exact byte positions.
+ * Whitespace detection uses token gaps to find blank lines
+ * between statements/comments.
+ */
+import { scanSync } from '@libpg-query/parser';
+/** Token type for -- line comments from PostgreSQL's lexer */
+const SQL_COMMENT = 275;
+/**
+ * Count blank lines in a string region.
+ * Returns 0 if there are fewer than 2 newlines (no blank line).
+ */
+function countBlankLines(text) {
+    let newlines = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === '\n')
+            newlines++;
+    }
+    return newlines >= 2 ? newlines - 1 : 0;
+}
+/**
+ * Scan SQL source text and extract all -- line comments and significant
+ * vertical whitespace (2+ consecutive newlines).
+ *
+ * Uses PostgreSQL's real lexer (via WASM scanSync) for comment detection,
+ * so all string literal types (single-quoted, dollar-quoted,
+ * escape strings, etc.) are handled correctly by the actual
+ * PostgreSQL scanner — no reimplementation needed.
+ */
+export function scanComments(sql) {
+    const elements = [];
+    let tokens;
+    try {
+        const scanResult = scanSync(sql);
+        tokens = scanResult.tokens;
+    }
+    catch {
+        return [];
+    }
+    let prevEnd = 0;
+    for (const token of tokens) {
+        if (token.start > prevEnd) {
+            const gap = sql.substring(prevEnd, token.start);
+            const blankLines = countBlankLines(gap);
+            if (blankLines > 0) {
+                elements.push({
+                    kind: 'whitespace',
+                    value: {
+                        lines: blankLines,
+                        start: prevEnd,
+                        end: token.start,
+                    }
+                });
+            }
+        }
+        if (token.tokenType === SQL_COMMENT) {
+            // A comment is "trailing" if no newline exists between the previous
+            // token's end and this comment's start (i.e. same line).
+            const gapBeforeComment = sql.substring(prevEnd, token.start);
+            const trailing = prevEnd > 0 && !gapBeforeComment.includes('\n');
+            elements.push({
+                kind: 'comment',
+                value: {
+                    type: 'line',
+                    text: sql.substring(token.start + 2, token.end), // strip --
+                    start: token.start,
+                    end: token.end,
+                    trailing,
+                }
+            });
+        }
+        prevEnd = token.end;
+    }
+    if (prevEnd < sql.length) {
+        const gap = sql.substring(prevEnd, sql.length);
+        const blankLines = countBlankLines(gap);
+        if (blankLines > 0) {
+            elements.push({
+                kind: 'whitespace',
+                value: {
+                    lines: blankLines,
+                    start: prevEnd,
+                    end: sql.length,
+                }
+            });
+        }
+    }
+    elements.sort((a, b) => a.value.start - b.value.start);
+    return elements;
+}

package/esm/types.js

@@ -0,0 +1,18 @@
+/**
+ * Type guard: check if a stmt entry is a RawComment node.
+ */
+export function isRawComment(stmt) {
+    return 'RawComment' in stmt;
+}
+/**
+ * Type guard: check if a stmt entry is a RawWhitespace node.
+ */
+export function isRawWhitespace(stmt) {
+    return 'RawWhitespace' in stmt;
+}
+/**
+ * Type guard: check if a stmt entry is a real RawStmt.
+ */
+export function isRawStmt(stmt) {
+    return 'stmt' in stmt;
+}

package/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * pgsql-parse — Comment and whitespace preserving PostgreSQL parser.
+ *
+ * Drop-in enhancement over pgsql-parser that preserves SQL -- line
+ * comments and vertical whitespace (blank lines) through
+ * parse→deparse round trips.
+ *
+ * Synthetic AST nodes:
+ * - RawComment: represents a SQL comment
+ * - RawWhitespace: represents significant vertical whitespace
+ *
+ * These nodes are interleaved with real RawStmt entries in the
+ * stmts array, ordered by byte position in the original source.
+ */
+export { parse, parseSync } from './parse';
+export { deparseEnhanced, deparseEnhancedSync, Deparser, DeparserOptions } from './deparse';
+export { deparse, deparseSync } from 'pgsql-deparser';
+export { loadModule } from '@libpg-query/parser';
+export { RawComment, RawWhitespace, EnhancedStmt, EnhancedParseResult, isRawComment, isRawWhitespace, isRawStmt, } from './types';
+export { scanComments, ScannedComment, ScannedWhitespace, ScannedElement } from './scanner';

package/index.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * pgsql-parse — Comment and whitespace preserving PostgreSQL parser.
+ *
+ * Drop-in enhancement over pgsql-parser that preserves SQL -- line
+ * comments and vertical whitespace (blank lines) through
+ * parse→deparse round trips.
+ *
+ * Synthetic AST nodes:
+ * - RawComment: represents a SQL comment
+ * - RawWhitespace: represents significant vertical whitespace
+ *
+ * These nodes are interleaved with real RawStmt entries in the
+ * stmts array, ordered by byte position in the original source.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanComments = exports.isRawStmt = exports.isRawWhitespace = exports.isRawComment = exports.loadModule = exports.deparseSync = exports.deparse = exports.Deparser = exports.deparseEnhancedSync = exports.deparseEnhanced = exports.parseSync = exports.parse = void 0;
+// Enhanced parse functions (comment/whitespace preserving)
+var parse_1 = require("./parse");
+Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return parse_1.parse; } });
+Object.defineProperty(exports, "parseSync", { enumerable: true, get: function () { return parse_1.parseSync; } });
+// Enhanced deparse function
+var deparse_1 = require("./deparse");
+Object.defineProperty(exports, "deparseEnhanced", { enumerable: true, get: function () { return deparse_1.deparseEnhanced; } });
+Object.defineProperty(exports, "deparseEnhancedSync", { enumerable: true, get: function () { return deparse_1.deparseEnhancedSync; } });
+Object.defineProperty(exports, "Deparser", { enumerable: true, get: function () { return deparse_1.Deparser; } });
+// Re-export standard deparse for non-enhanced use
+var pgsql_deparser_1 = require("pgsql-deparser");
+Object.defineProperty(exports, "deparse", { enumerable: true, get: function () { return pgsql_deparser_1.deparse; } });
+Object.defineProperty(exports, "deparseSync", { enumerable: true, get: function () { return pgsql_deparser_1.deparseSync; } });
+// Re-export loadModule from @libpg-query/parser
+var parser_1 = require("@libpg-query/parser");
+Object.defineProperty(exports, "loadModule", { enumerable: true, get: function () { return parser_1.loadModule; } });
+// Types
+var types_1 = require("./types");
+Object.defineProperty(exports, "isRawComment", { enumerable: true, get: function () { return types_1.isRawComment; } });
+Object.defineProperty(exports, "isRawWhitespace", { enumerable: true, get: function () { return types_1.isRawWhitespace; } });
+Object.defineProperty(exports, "isRawStmt", { enumerable: true, get: function () { return types_1.isRawStmt; } });
+// Scanner (for advanced use)
+var scanner_1 = require("./scanner");
+Object.defineProperty(exports, "scanComments", { enumerable: true, get: function () { return scanner_1.scanComments; } });

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pgsql-parse",
+  "version": "0.2.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Comment and whitespace preserving PostgreSQL parser",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/pgsql-parser",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/pgsql-parser"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/pgsql-parser/issues"
+  },
+  "scripts": {
+    "copy": "makage assets",
+    "clean": "makage clean dist",
+    "prepublishOnly": "npm run build",
+    "build": "npm run clean && tsc && tsc -p tsconfig.esm.json && npm run copy",
+    "build:dev": "npm run clean && tsc --declarationMap && tsc -p tsconfig.esm.json && npm run copy",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "sql",
+    "postgres",
+    "postgresql",
+    "pg",
+    "parser",
+    "comment",
+    "whitespace",
+    "round-trip"
+  ],
+  "dependencies": {
+    "@libpg-query/parser": "^17.6.10",
+    "@pgsql/types": "^17.6.2",
+    "pgsql-deparser": "17.18.3"
+  },
+  "devDependencies": {
+    "makage": "^0.1.8"
+  },
+  "gitHead": "6571608759a472a0fb8f462737056e8e5a2bb0dc"
+}

package/parse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Enhanced parse functions that preserve comments and vertical whitespace
+ * by interleaving synthetic RawComment and RawWhitespace nodes into the
+ * parse result's stmts array.
+ */
+import { EnhancedParseResult } from './types';
+/**
+ * Parse SQL with comment and whitespace preservation (async).
+ *
+ * Returns an EnhancedParseResult where the stmts array contains
+ * real RawStmt entries interleaved with synthetic RawComment and
+ * RawWhitespace nodes, all ordered by their byte position in the
+ * original source text.
+ */
+export declare function parse(sql: string): Promise<EnhancedParseResult>;
+/**
+ * Parse SQL with comment and whitespace preservation (sync).
+ */
+export declare function parseSync(sql: string): EnhancedParseResult;

package/parse.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Enhanced parse functions that preserve comments and vertical whitespace
+ * by interleaving synthetic RawComment and RawWhitespace nodes into the
+ * parse result's stmts array.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = parse;
+exports.parseSync = parseSync;
+const parser_1 = require("@libpg-query/parser");
+const scanner_1 = require("./scanner");
+/**
+ * Find the actual SQL start position for a statement by skipping
+ * past any comments and whitespace that the parser included in
+ * the stmt_location..stmt_location+stmt_len range.
+ *
+ * The parser's stmt_location often includes preceding whitespace
+ * and comments that were stripped during parsing. We need the
+ * position of the first real SQL token.
+ */
+function findActualSqlStart(sql, stmtLoc, elements) {
+    let pos = stmtLoc;
+    // Iteratively skip whitespace and any scanned elements (comments/whitespace)
+    // that start at or after our current position
+    let changed = true;
+    while (changed) {
+        changed = false;
+        // Skip whitespace characters
+        while (pos < sql.length && /\s/.test(sql[pos])) {
+            pos++;
+            changed = true;
+        }
+        // Skip past any scanned element that starts at current position
+        for (const elem of elements) {
+            if (elem.value.start === pos || (elem.value.start >= stmtLoc && elem.value.start < pos + 1 && elem.value.end > pos)) {
+                if (elem.value.end > pos) {
+                    pos = elem.value.end;
+                    changed = true;
+                }
+            }
+        }
+    }
+    return pos;
+}
+function buildStmtRanges(stmts, sql, elements) {
+    return stmts.map(stmt => {
+        const loc = stmt.stmt_location ?? 0;
+        const actualStart = findActualSqlStart(sql, loc, elements);
+        const len = stmt.stmt_len ?? sql.length - loc;
+        return { actualStart, end: loc + len };
+    });
+}
+function interleave(parseResult, sql, elements) {
+    const stmts = parseResult.stmts ?? [];
+    const items = [];
+    const ranges = buildStmtRanges(stmts, sql, elements);
+    // Add scanned elements (comments and whitespace)
+    for (const elem of elements) {
+        if (elem.kind === 'comment') {
+            // Check if this comment falls inside a statement's byte range.
+            // If so, hoist it above that statement instead of leaving it
+            // at its original position (which would place it after the
+            // statement or trailing at the wrong spot).
+            let hoistedPosition = null;
+            for (const range of ranges) {
+                if (elem.value.start > range.actualStart && elem.value.start < range.end) {
+                    hoistedPosition = range.actualStart;
+                    break;
+                }
+            }
+            items.push({
+                position: hoistedPosition ?? elem.value.start,
+                priority: 0,
+                entry: {
+                    RawComment: {
+                        type: elem.value.type,
+                        text: elem.value.text,
+                        location: elem.value.start,
+                        // Only preserve trailing flag when NOT hoisted —
+                        // a hoisted comment becomes a standalone line above the statement.
+                        ...(hoistedPosition == null && elem.value.trailing ? { trailing: true } : {}),
+                    }
+                }
+            });
+        }
+        else {
+            items.push({
+                position: elem.value.start,
+                priority: 1, // whitespace sorts after comments at same position
+                entry: {
+                    RawWhitespace: {
+                        lines: elem.value.lines,
+                        location: elem.value.start,
+                    }
+                }
+            });
+        }
+    }
+    // Add parsed statements with their actual SQL start position
+    for (let i = 0; i < stmts.length; i++) {
+        items.push({
+            position: ranges[i].actualStart,
+            priority: 2, // statements sort after comments and whitespace
+            entry: stmts[i],
+        });
+    }
+    // Sort by position, then by priority
+    items.sort((a, b) => {
+        if (a.position !== b.position)
+            return a.position - b.position;
+        return a.priority - b.priority;
+    });
+    return {
+        version: parseResult.version,
+        stmts: items.map(item => item.entry),
+    };
+}
+/**
+ * Parse SQL with comment and whitespace preservation (async).
+ *
+ * Returns an EnhancedParseResult where the stmts array contains
+ * real RawStmt entries interleaved with synthetic RawComment and
+ * RawWhitespace nodes, all ordered by their byte position in the
+ * original source text.
+ */
+async function parse(sql) {
+    const parseResult = await (0, parser_1.parse)(sql);
+    const elements = (0, scanner_1.scanComments)(sql);
+    return interleave(parseResult, sql, elements);
+}
+/**
+ * Parse SQL with comment and whitespace preservation (sync).
+ */
+function parseSync(sql) {
+    const parseResult = (0, parser_1.parseSync)(sql);
+    const elements = (0, scanner_1.scanComments)(sql);
+    return interleave(parseResult, sql, elements);
+}

package/scanner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Scanner for extracting comments and vertical whitespace
+ * from PostgreSQL SQL source text.
+ *
+ * Uses PostgreSQL's real lexer via @libpg-query/parser's scanSync()
+ * to identify SQL_COMMENT tokens with exact byte positions.
+ * Whitespace detection uses token gaps to find blank lines
+ * between statements/comments.
+ */
+export interface ScannedComment {
+    type: 'line';
+    /** The comment text (without the -- delimiter) */
+    text: string;
+    /** Byte offset of the start of the comment (including --) */
+    start: number;
+    /** Byte offset of the end of the comment (exclusive) */
+    end: number;
+    /** True if this comment is on the same line as a preceding token (trailing comment) */
+    trailing: boolean;
+}
+export interface ScannedWhitespace {
+    /** Number of blank lines (consecutive \n\n sequences) */
+    lines: number;
+    /** Byte offset of the start of the whitespace region */
+    start: number;
+    /** Byte offset of the end of the whitespace region */
+    end: number;
+}
+export type ScannedElement = {
+    kind: 'comment';
+    value: ScannedComment;
+} | {
+    kind: 'whitespace';
+    value: ScannedWhitespace;
+};
+/**
+ * Scan SQL source text and extract all -- line comments and significant
+ * vertical whitespace (2+ consecutive newlines).
+ *
+ * Uses PostgreSQL's real lexer (via WASM scanSync) for comment detection,
+ * so all string literal types (single-quoted, dollar-quoted,
+ * escape strings, etc.) are handled correctly by the actual
+ * PostgreSQL scanner — no reimplementation needed.
+ */
+export declare function scanComments(sql: string): ScannedElement[];

package/scanner.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Scanner for extracting comments and vertical whitespace
+ * from PostgreSQL SQL source text.
+ *
+ * Uses PostgreSQL's real lexer via @libpg-query/parser's scanSync()
+ * to identify SQL_COMMENT tokens with exact byte positions.
+ * Whitespace detection uses token gaps to find blank lines
+ * between statements/comments.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanComments = scanComments;
+const parser_1 = require("@libpg-query/parser");
+/** Token type for -- line comments from PostgreSQL's lexer */
+const SQL_COMMENT = 275;
+/**
+ * Count blank lines in a string region.
+ * Returns 0 if there are fewer than 2 newlines (no blank line).
+ */
+function countBlankLines(text) {
+    let newlines = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === '\n')
+            newlines++;
+    }
+    return newlines >= 2 ? newlines - 1 : 0;
+}
+/**
+ * Scan SQL source text and extract all -- line comments and significant
+ * vertical whitespace (2+ consecutive newlines).
+ *
+ * Uses PostgreSQL's real lexer (via WASM scanSync) for comment detection,
+ * so all string literal types (single-quoted, dollar-quoted,
+ * escape strings, etc.) are handled correctly by the actual
+ * PostgreSQL scanner — no reimplementation needed.
+ */
+function scanComments(sql) {
+    const elements = [];
+    let tokens;
+    try {
+        const scanResult = (0, parser_1.scanSync)(sql);
+        tokens = scanResult.tokens;
+    }
+    catch {
+        return [];
+    }
+    let prevEnd = 0;
+    for (const token of tokens) {
+        if (token.start > prevEnd) {
+            const gap = sql.substring(prevEnd, token.start);
+            const blankLines = countBlankLines(gap);
+            if (blankLines > 0) {
+                elements.push({
+                    kind: 'whitespace',
+                    value: {
+                        lines: blankLines,
+                        start: prevEnd,
+                        end: token.start,
+                    }
+                });
+            }
+        }
+        if (token.tokenType === SQL_COMMENT) {
+            // A comment is "trailing" if no newline exists between the previous
+            // token's end and this comment's start (i.e. same line).
+            const gapBeforeComment = sql.substring(prevEnd, token.start);
+            const trailing = prevEnd > 0 && !gapBeforeComment.includes('\n');
+            elements.push({
+                kind: 'comment',
+                value: {
+                    type: 'line',
+                    text: sql.substring(token.start + 2, token.end), // strip --
+                    start: token.start,
+                    end: token.end,
+                    trailing,
+                }
+            });
+        }
+        prevEnd = token.end;
+    }
+    if (prevEnd < sql.length) {
+        const gap = sql.substring(prevEnd, sql.length);
+        const blankLines = countBlankLines(gap);
+        if (blankLines > 0) {
+            elements.push({
+                kind: 'whitespace',
+                value: {
+                    lines: blankLines,
+                    start: prevEnd,
+                    end: sql.length,
+                }
+            });
+        }
+    }
+    elements.sort((a, b) => a.value.start - b.value.start);
+    return elements;
+}

package/types.d.ts

@@ -0,0 +1,59 @@
+import { RawStmt } from '@pgsql/types';
+/**
+ * Synthetic AST node representing a SQL comment.
+ * Not produced by PostgreSQL's parser — injected by pgsql-parse
+ * to preserve comments through parse→deparse round trips.
+ */
+export interface RawComment {
+    /** Always 'line' — only -- comments are supported */
+    type: 'line';
+    /** The comment text (without the -- delimiter) */
+    text: string;
+    /** Byte offset in the original source (for ordering) */
+    location: number;
+    /** True if this comment is on the same line as the preceding statement */
+    trailing?: boolean;
+}
+/**
+ * Synthetic AST node representing significant vertical whitespace.
+ * Represents one or more blank lines between statements.
+ */
+export interface RawWhitespace {
+    /** Number of blank lines */
+    lines: number;
+    /** Byte offset in the original source (for ordering) */
+    location: number;
+}
+/**
+ * A statement entry that can hold either a real RawStmt or a synthetic node.
+ * The stmts array in EnhancedParseResult contains these.
+ */
+export type EnhancedStmt = RawStmt | {
+    RawComment: RawComment;
+} | {
+    RawWhitespace: RawWhitespace;
+};
+/**
+ * Enhanced parse result that includes synthetic comment and whitespace nodes
+ * interleaved with the real RawStmt entries by byte position.
+ */
+export interface EnhancedParseResult {
+    version: number;
+    stmts: EnhancedStmt[];
+}
+/**
+ * Type guard: check if a stmt entry is a RawComment node.
+ */
+export declare function isRawComment(stmt: EnhancedStmt): stmt is {
+    RawComment: RawComment;
+};
+/**
+ * Type guard: check if a stmt entry is a RawWhitespace node.
+ */
+export declare function isRawWhitespace(stmt: EnhancedStmt): stmt is {
+    RawWhitespace: RawWhitespace;
+};
+/**
+ * Type guard: check if a stmt entry is a real RawStmt.
+ */
+export declare function isRawStmt(stmt: EnhancedStmt): stmt is RawStmt;

package/types.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRawComment = isRawComment;
+exports.isRawWhitespace = isRawWhitespace;
+exports.isRawStmt = isRawStmt;
+/**
+ * Type guard: check if a stmt entry is a RawComment node.
+ */
+function isRawComment(stmt) {
+    return 'RawComment' in stmt;
+}
+/**
+ * Type guard: check if a stmt entry is a RawWhitespace node.
+ */
+function isRawWhitespace(stmt) {
+    return 'RawWhitespace' in stmt;
+}
+/**
+ * Type guard: check if a stmt entry is a real RawStmt.
+ */
+function isRawStmt(stmt) {
+    return 'stmt' in stmt;
+}