plpgsql-parse 0.2.0

package/esm/parse.js

@@ -0,0 +1,119 @@
+/**
+ * Enhanced parse that wraps plpgsql-parser and pgsql-parse to preserve
+ * both outer SQL comments/whitespace AND comments inside PL/pgSQL
+ * function bodies.
+ *
+ * This module does NOT modify plpgsql-parser or pgsql-parse — it
+ * composes them and adds body-comment metadata on top.
+ */
+import { parseSync as parseSqlSync, loadModule, } from '@libpg-query/parser';
+import { parseSync as pgsqlParseSync } from 'pgsql-parse';
+import { scanBodyComments } from './body-scanner';
+export { loadModule };
+/**
+ * Check if a statement is a CREATE FUNCTION with LANGUAGE plpgsql.
+ */
+function isPlpgsqlFunction(stmt) {
+    const createFunctionStmt = stmt?.CreateFunctionStmt;
+    if (!createFunctionStmt)
+        return false;
+    const options = createFunctionStmt.options;
+    if (!options)
+        return false;
+    for (const opt of options) {
+        if (opt?.DefElem?.defname === 'language') {
+            const arg = opt.DefElem.arg;
+            if (arg?.String?.sval) {
+                return arg.String.sval.toLowerCase() === 'plpgsql';
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Extract the raw function body and dollar-quote delimiter from a
+ * CREATE FUNCTION statement's AST options.
+ */
+function getBodyFromOptions(options) {
+    if (!options)
+        return null;
+    for (const opt of options) {
+        if (opt?.DefElem?.defname === 'as') {
+            const arg = opt.DefElem.arg;
+            if (arg?.List?.items?.[0]?.String?.sval) {
+                return { raw: arg.List.items[0].String.sval, delimiter: '$$' };
+            }
+            if (arg?.String?.sval) {
+                return { raw: arg.String.sval, delimiter: '$$' };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parse SQL with full comment preservation — both outer SQL level
+ * (between statements) and inside PL/pgSQL function bodies.
+ *
+ * Combines:
+ * - pgsql-parse's scanner for outer SQL comments/whitespace
+ * - plpgsql-parser's PL/pgSQL body parsing + hydration
+ * - body-scanner for function body comments
+ */
+export function parseSync(sql) {
+    // 1. Outer SQL: use pgsql-parse for comment/whitespace preservation
+    const enhanced = pgsqlParseSync(sql);
+    // 2. Also parse with the standard SQL parser to get statement ASTs
+    const sqlResult = parseSqlSync(sql);
+    const stmts = sqlResult.stmts ?? [];
+    // 3. For each PL/pgSQL function, extract body comments
+    const functions = [];
+    for (let i = 0; i < stmts.length; i++) {
+        const rawStmt = stmts[i];
+        const stmt = rawStmt?.stmt;
+        if (!stmt || !isPlpgsqlFunction(stmt))
+            continue;
+        const createFunctionStmt = stmt.CreateFunctionStmt;
+        const body = getBodyFromOptions(createFunctionStmt.options);
+        if (!body)
+            continue;
+        // Scan the body for comments
+        const comments = scanBodyComments(body.raw);
+        if (comments.length === 0)
+            continue;
+        // Find the matching index in the enhanced stmts array.
+        // The enhanced array may have synthetic nodes interleaved,
+        // so we match by searching for the RawStmt at the right position.
+        const enhancedIndex = findEnhancedStmtIndex(enhanced, i);
+        functions.push({
+            stmtIndex: enhancedIndex,
+            originalBody: body.raw,
+            delimiter: body.delimiter,
+            comments,
+        });
+    }
+    return { enhanced, functions };
+}
+/**
+ * Async version of parseSync.
+ */
+export async function parse(sql) {
+    return parseSync(sql);
+}
+/**
+ * Find the index of the i-th RawStmt in the enhanced stmts array.
+ * The enhanced array interleaves RawComment and RawWhitespace nodes,
+ * so the n-th real statement isn't at index n.
+ */
+function findEnhancedStmtIndex(enhanced, rawStmtIndex) {
+    let realCount = 0;
+    for (let j = 0; j < enhanced.stmts.length; j++) {
+        const entry = enhanced.stmts[j];
+        if ('stmt' in entry) {
+            if (realCount === rawStmtIndex)
+                return j;
+            realCount++;
+        }
+    }
+    // Fallback: return the rawStmtIndex (shouldn't happen)
+    return rawStmtIndex;
+}

package/esm/return-info.js

@@ -0,0 +1,62 @@
+/**
+ * Return info extraction for PL/pgSQL functions.
+ *
+ * Re-exports the upstream helper from plpgsql-parser's return-info module
+ * pattern, but implemented locally to avoid depending on plpgsql-parser
+ * (which would create a circular dependency).
+ */
+/**
+ * Extract return type information from a CreateFunctionStmt AST node.
+ */
+export function getReturnInfo(createFunctionStmt) {
+    if (!createFunctionStmt) {
+        return { kind: 'scalar' };
+    }
+    // Procedures have implicit void return
+    if (createFunctionStmt.is_procedure) {
+        return { kind: 'void' };
+    }
+    // Check for OUT/INOUT/TABLE parameters
+    if (createFunctionStmt.parameters && Array.isArray(createFunctionStmt.parameters)) {
+        const hasOutParams = createFunctionStmt.parameters.some((param) => {
+            const fp = param?.FunctionParameter;
+            if (!fp)
+                return false;
+            const mode = fp.mode;
+            return mode === 'FUNC_PARAM_OUT' ||
+                mode === 'FUNC_PARAM_INOUT' ||
+                mode === 'FUNC_PARAM_TABLE';
+        });
+        if (hasOutParams) {
+            return { kind: 'out_params' };
+        }
+    }
+    // Check the return type
+    const returnType = createFunctionStmt.returnType;
+    if (!returnType) {
+        return { kind: 'void' };
+    }
+    // SETOF
+    if (returnType.setof) {
+        return { kind: 'setof' };
+    }
+    // Extract type name
+    const names = returnType.names
+        ?.map((n) => n?.String?.sval)
+        .filter((s) => typeof s === 'string') ?? [];
+    const lastName = names[names.length - 1]?.toLowerCase() ?? '';
+    if (lastName === 'void')
+        return { kind: 'void' };
+    if (lastName === 'trigger')
+        return { kind: 'trigger' };
+    return { kind: 'scalar' };
+}
+/**
+ * Get return info from a parsed function's stmt field.
+ */
+export function getReturnInfoFromParsedFunction(parsedFunction) {
+    if (!parsedFunction?.stmt) {
+        return { kind: 'scalar' };
+    }
+    return getReturnInfo(parsedFunction.stmt);
+}

package/esm/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for plpgsql-parse — comment-preserving PL/pgSQL parser.
+ *
+ * Re-uses pgsql-parse's EnhancedParseResult for the outer SQL level
+ * and adds body-level comment metadata for PL/pgSQL function bodies.
+ */
+export {};

package/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * plpgsql-parse — Comment and whitespace preserving PL/pgSQL parser.
+ *
+ * Drop-in enhancement over plpgsql-parser that preserves SQL -- line
+ * comments and vertical whitespace (blank lines) through parse→deparse
+ * round trips, both at the outer SQL level (between statements) and
+ * inside PL/pgSQL function bodies.
+ *
+ * This package wraps plpgsql-parser, plpgsql-deparser, and pgsql-parse
+ * without modifying any of them.
+ */
+export { parse, parseSync, loadModule } from './parse';
+export { deparse, deparseSync, type DeparseOptions } from './deparse';
+export type { PlpgsqlParseResult, FunctionComments, BodyComment, } from './types';
+export { scanBodyComments, groupCommentsByAnchor, type CommentGroup } from './body-scanner';
+export type { EnhancedParseResult, EnhancedStmt, RawComment, RawWhitespace } from 'pgsql-parse';
+export { isRawComment, isRawWhitespace, isRawStmt } from 'pgsql-parse';

package/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * plpgsql-parse — Comment and whitespace preserving PL/pgSQL parser.
+ *
+ * Drop-in enhancement over plpgsql-parser that preserves SQL -- line
+ * comments and vertical whitespace (blank lines) through parse→deparse
+ * round trips, both at the outer SQL level (between statements) and
+ * inside PL/pgSQL function bodies.
+ *
+ * This package wraps plpgsql-parser, plpgsql-deparser, and pgsql-parse
+ * without modifying any of them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRawStmt = exports.isRawWhitespace = exports.isRawComment = exports.groupCommentsByAnchor = exports.scanBodyComments = exports.deparseSync = exports.deparse = exports.loadModule = 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; } });
+Object.defineProperty(exports, "loadModule", { enumerable: true, get: function () { return parse_1.loadModule; } });
+// Enhanced deparse functions
+var deparse_1 = require("./deparse");
+Object.defineProperty(exports, "deparse", { enumerable: true, get: function () { return deparse_1.deparse; } });
+Object.defineProperty(exports, "deparseSync", { enumerable: true, get: function () { return deparse_1.deparseSync; } });
+// Body scanner (for advanced use)
+var body_scanner_1 = require("./body-scanner");
+Object.defineProperty(exports, "scanBodyComments", { enumerable: true, get: function () { return body_scanner_1.scanBodyComments; } });
+Object.defineProperty(exports, "groupCommentsByAnchor", { enumerable: true, get: function () { return body_scanner_1.groupCommentsByAnchor; } });
+var pgsql_parse_1 = require("pgsql-parse");
+Object.defineProperty(exports, "isRawComment", { enumerable: true, get: function () { return pgsql_parse_1.isRawComment; } });
+Object.defineProperty(exports, "isRawWhitespace", { enumerable: true, get: function () { return pgsql_parse_1.isRawWhitespace; } });
+Object.defineProperty(exports, "isRawStmt", { enumerable: true, get: function () { return pgsql_parse_1.isRawStmt; } });

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "plpgsql-parse",
+  "version": "0.2.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Comment and whitespace preserving PL/pgSQL 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",
+    "plpgsql",
+    "parser",
+    "comment",
+    "whitespace",
+    "round-trip"
+  ],
+  "dependencies": {
+    "@libpg-query/parser": "^17.6.10",
+    "@pgsql/types": "^17.6.2",
+    "pgsql-deparser": "17.18.3",
+    "pgsql-parse": "0.2.0",
+    "plpgsql-deparser": "0.7.7"
+  },
+  "devDependencies": {
+    "makage": "^0.1.8"
+  },
+  "gitHead": "b4dd31a9a1b34bdb74c13b5cf597bf8910b1762d"
+}

package/parse.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Enhanced parse that wraps plpgsql-parser and pgsql-parse to preserve
+ * both outer SQL comments/whitespace AND comments inside PL/pgSQL
+ * function bodies.
+ *
+ * This module does NOT modify plpgsql-parser or pgsql-parse — it
+ * composes them and adds body-comment metadata on top.
+ */
+import { loadModule } from '@libpg-query/parser';
+import type { PlpgsqlParseResult } from './types';
+export { loadModule };
+/**
+ * Parse SQL with full comment preservation — both outer SQL level
+ * (between statements) and inside PL/pgSQL function bodies.
+ *
+ * Combines:
+ * - pgsql-parse's scanner for outer SQL comments/whitespace
+ * - plpgsql-parser's PL/pgSQL body parsing + hydration
+ * - body-scanner for function body comments
+ */
+export declare function parseSync(sql: string): PlpgsqlParseResult;
+/**
+ * Async version of parseSync.
+ */
+export declare function parse(sql: string): Promise<PlpgsqlParseResult>;

package/parse.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Enhanced parse that wraps plpgsql-parser and pgsql-parse to preserve
+ * both outer SQL comments/whitespace AND comments inside PL/pgSQL
+ * function bodies.
+ *
+ * This module does NOT modify plpgsql-parser or pgsql-parse — it
+ * composes them and adds body-comment metadata on top.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadModule = void 0;
+exports.parseSync = parseSync;
+exports.parse = parse;
+const parser_1 = require("@libpg-query/parser");
+Object.defineProperty(exports, "loadModule", { enumerable: true, get: function () { return parser_1.loadModule; } });
+const pgsql_parse_1 = require("pgsql-parse");
+const body_scanner_1 = require("./body-scanner");
+/**
+ * Check if a statement is a CREATE FUNCTION with LANGUAGE plpgsql.
+ */
+function isPlpgsqlFunction(stmt) {
+    const createFunctionStmt = stmt?.CreateFunctionStmt;
+    if (!createFunctionStmt)
+        return false;
+    const options = createFunctionStmt.options;
+    if (!options)
+        return false;
+    for (const opt of options) {
+        if (opt?.DefElem?.defname === 'language') {
+            const arg = opt.DefElem.arg;
+            if (arg?.String?.sval) {
+                return arg.String.sval.toLowerCase() === 'plpgsql';
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Extract the raw function body and dollar-quote delimiter from a
+ * CREATE FUNCTION statement's AST options.
+ */
+function getBodyFromOptions(options) {
+    if (!options)
+        return null;
+    for (const opt of options) {
+        if (opt?.DefElem?.defname === 'as') {
+            const arg = opt.DefElem.arg;
+            if (arg?.List?.items?.[0]?.String?.sval) {
+                return { raw: arg.List.items[0].String.sval, delimiter: '$$' };
+            }
+            if (arg?.String?.sval) {
+                return { raw: arg.String.sval, delimiter: '$$' };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parse SQL with full comment preservation — both outer SQL level
+ * (between statements) and inside PL/pgSQL function bodies.
+ *
+ * Combines:
+ * - pgsql-parse's scanner for outer SQL comments/whitespace
+ * - plpgsql-parser's PL/pgSQL body parsing + hydration
+ * - body-scanner for function body comments
+ */
+function parseSync(sql) {
+    // 1. Outer SQL: use pgsql-parse for comment/whitespace preservation
+    const enhanced = (0, pgsql_parse_1.parseSync)(sql);
+    // 2. Also parse with the standard SQL parser to get statement ASTs
+    const sqlResult = (0, parser_1.parseSync)(sql);
+    const stmts = sqlResult.stmts ?? [];
+    // 3. For each PL/pgSQL function, extract body comments
+    const functions = [];
+    for (let i = 0; i < stmts.length; i++) {
+        const rawStmt = stmts[i];
+        const stmt = rawStmt?.stmt;
+        if (!stmt || !isPlpgsqlFunction(stmt))
+            continue;
+        const createFunctionStmt = stmt.CreateFunctionStmt;
+        const body = getBodyFromOptions(createFunctionStmt.options);
+        if (!body)
+            continue;
+        // Scan the body for comments
+        const comments = (0, body_scanner_1.scanBodyComments)(body.raw);
+        if (comments.length === 0)
+            continue;
+        // Find the matching index in the enhanced stmts array.
+        // The enhanced array may have synthetic nodes interleaved,
+        // so we match by searching for the RawStmt at the right position.
+        const enhancedIndex = findEnhancedStmtIndex(enhanced, i);
+        functions.push({
+            stmtIndex: enhancedIndex,
+            originalBody: body.raw,
+            delimiter: body.delimiter,
+            comments,
+        });
+    }
+    return { enhanced, functions };
+}
+/**
+ * Async version of parseSync.
+ */
+async function parse(sql) {
+    return parseSync(sql);
+}
+/**
+ * Find the index of the i-th RawStmt in the enhanced stmts array.
+ * The enhanced array interleaves RawComment and RawWhitespace nodes,
+ * so the n-th real statement isn't at index n.
+ */
+function findEnhancedStmtIndex(enhanced, rawStmtIndex) {
+    let realCount = 0;
+    for (let j = 0; j < enhanced.stmts.length; j++) {
+        const entry = enhanced.stmts[j];
+        if ('stmt' in entry) {
+            if (realCount === rawStmtIndex)
+                return j;
+            realCount++;
+        }
+    }
+    // Fallback: return the rawStmtIndex (shouldn't happen)
+    return rawStmtIndex;
+}

package/return-info.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Return info extraction for PL/pgSQL functions.
+ *
+ * Re-exports the upstream helper from plpgsql-parser's return-info module
+ * pattern, but implemented locally to avoid depending on plpgsql-parser
+ * (which would create a circular dependency).
+ */
+import type { ReturnInfo, ReturnInfoKind } from 'plpgsql-deparser';
+/**
+ * Extract return type information from a CreateFunctionStmt AST node.
+ */
+export declare function getReturnInfo(createFunctionStmt: any): ReturnInfo;
+/**
+ * Get return info from a parsed function's stmt field.
+ */
+export declare function getReturnInfoFromParsedFunction(parsedFunction: any): ReturnInfo;
+export type { ReturnInfo, ReturnInfoKind };

package/return-info.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Return info extraction for PL/pgSQL functions.
+ *
+ * Re-exports the upstream helper from plpgsql-parser's return-info module
+ * pattern, but implemented locally to avoid depending on plpgsql-parser
+ * (which would create a circular dependency).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getReturnInfo = getReturnInfo;
+exports.getReturnInfoFromParsedFunction = getReturnInfoFromParsedFunction;
+/**
+ * Extract return type information from a CreateFunctionStmt AST node.
+ */
+function getReturnInfo(createFunctionStmt) {
+    if (!createFunctionStmt) {
+        return { kind: 'scalar' };
+    }
+    // Procedures have implicit void return
+    if (createFunctionStmt.is_procedure) {
+        return { kind: 'void' };
+    }
+    // Check for OUT/INOUT/TABLE parameters
+    if (createFunctionStmt.parameters && Array.isArray(createFunctionStmt.parameters)) {
+        const hasOutParams = createFunctionStmt.parameters.some((param) => {
+            const fp = param?.FunctionParameter;
+            if (!fp)
+                return false;
+            const mode = fp.mode;
+            return mode === 'FUNC_PARAM_OUT' ||
+                mode === 'FUNC_PARAM_INOUT' ||
+                mode === 'FUNC_PARAM_TABLE';
+        });
+        if (hasOutParams) {
+            return { kind: 'out_params' };
+        }
+    }
+    // Check the return type
+    const returnType = createFunctionStmt.returnType;
+    if (!returnType) {
+        return { kind: 'void' };
+    }
+    // SETOF
+    if (returnType.setof) {
+        return { kind: 'setof' };
+    }
+    // Extract type name
+    const names = returnType.names
+        ?.map((n) => n?.String?.sval)
+        .filter((s) => typeof s === 'string') ?? [];
+    const lastName = names[names.length - 1]?.toLowerCase() ?? '';
+    if (lastName === 'void')
+        return { kind: 'void' };
+    if (lastName === 'trigger')
+        return { kind: 'trigger' };
+    return { kind: 'scalar' };
+}
+/**
+ * Get return info from a parsed function's stmt field.
+ */
+function getReturnInfoFromParsedFunction(parsedFunction) {
+    if (!parsedFunction?.stmt) {
+        return { kind: 'scalar' };
+    }
+    return getReturnInfo(parsedFunction.stmt);
+}

package/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Types for plpgsql-parse — comment-preserving PL/pgSQL parser.
+ *
+ * Re-uses pgsql-parse's EnhancedParseResult for the outer SQL level
+ * and adds body-level comment metadata for PL/pgSQL function bodies.
+ */
+import type { EnhancedParseResult } from 'pgsql-parse';
+/**
+ * A comment extracted from a PL/pgSQL function body.
+ */
+export interface BodyComment {
+    /** The full comment text including -- prefix */
+    text: string;
+    /** 1-based line number within the function body */
+    lineNo: number;
+    /** Whether this is a standalone comment line (vs inline after code) */
+    standalone: boolean;
+}
+/**
+ * Metadata about a PL/pgSQL function's body comments,
+ * stored alongside the parsed function data.
+ */
+export interface FunctionComments {
+    /** Index of the RawStmt in the EnhancedParseResult.stmts array */
+    stmtIndex: number;
+    /** The raw body text extracted from the dollar-quoted string */
+    originalBody: string;
+    /** The dollar-quote delimiter (e.g., '$$', '$fn$') */
+    delimiter: string;
+    /** Comments found in the body, ordered by line number */
+    comments: BodyComment[];
+}
+/**
+ * The result of parsing SQL with plpgsql-parse.
+ * Extends pgsql-parse's EnhancedParseResult with PL/pgSQL body comment info.
+ */
+export interface PlpgsqlParseResult {
+    /** The outer SQL parse result with comments/whitespace preserved */
+    enhanced: EnhancedParseResult;
+    /** Comment metadata for each PL/pgSQL function found */
+    functions: FunctionComments[];
+}

package/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Types for plpgsql-parse — comment-preserving PL/pgSQL parser.
+ *
+ * Re-uses pgsql-parse's EnhancedParseResult for the outer SQL level
+ * and adds body-level comment metadata for PL/pgSQL function bodies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });