Skip to content

README.md

Latest commit

 

History

History
82 lines (58 loc) · 2.89 KB

README.md

File metadata and controls

82 lines (58 loc) · 2.89 KB

pgsql-parse

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

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

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

import { parseSync, deparseEnhanced, loadModule } from 'pgsql-parse';

await loadModule();

const result = parseSync('-- comment\nSELECT 1;');
const sql = deparseEnhanced(result);

Type Guards

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 -- official maintainer since 2018 and architect of the current implementation
  • Lukas Fittl for libpg_query -- the core PostgreSQL parser that powers this project