Registry / serialization / pg-proto-parser

pg-proto-parser

JSON →
library1.30.5jsnpmunverified

The `pg-proto-parser` library is a TypeScript project designed to parse Protocol Buffers (`.proto`) definitions specifically for `pganalyze/libpg_query` PostgreSQL Abstract Syntax Tree (AST) structures. It does not parse raw SQL queries or the PostgreSQL wire protocol directly. Instead, its primary function is to generate TypeScript interfaces, utility functions, and JSON mappings for the enums and messages defined within these PostgreSQL-related protobuf schemas. This generated code facilitates the creation of type-safe AST nodes and simplifies enum value conversions, serving as a foundational tool for other PostgreSQL tooling like `launchql/pgsql-parser` for maintainable upgrades. The package is currently at version 1.30.5 and appears to be actively maintained, offering a crucial layer for developers working with PostgreSQL's internal query representation in a type-safe TypeScript environment.

npm install pg-proto-parser
INSTALL
IMPORT
SIG · PG-PROTO-PARSER
P
pg-proto-parser
serializationjavascriptv1.30.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PgProtoParser
import { PgProtoParser } from 'pg-proto-parser';
const PgProtoParser = require('pg-proto-parser');
The library is written in TypeScript and primarily designed for ESM environments. CommonJS `require` syntax is generally incorrect or requires bundler configuration.
PgProtoParserOptions
import type { PgProtoParserOptions } from 'pg-proto-parser';
import { PgProtoParserOptions } from 'pg-proto-parser';
This is a TypeScript type/interface, so use `import type` for clarity and to avoid bundling issues if using older TypeScript versions or specific bundler configurations.
GeneratedTypes
import type { A_Const } from 'pg-proto-parser/types';
import { A_Const } from 'pg-proto-parser';
Many of the useful exports are generated types, enums, or utilities from parsing the protobuf definitions. These are often located in subpaths like `pg-proto-parser/types` or `pg-proto-parser/enums` rather than the main entry point.

This quickstart demonstrates how to initialize `PgProtoParser` with a dummy protobuf schema, configure output options, and generate corresponding TypeScript interfaces, enums, and utility files into a specified directory.

import { PgProtoParser } from 'pg-proto-parser'; import { readFileSync, mkdirSync, writeFileSync } from 'fs'; import { resolve } from 'path'; const protoContent = ` syntax = "proto3"; package pg_query; message Node { int32 location = 1; } message A_Const { Node node = 1; oneof val { int64 ival = 2; // integer bool bval = 3; // boolean string sval = 4; // string } int32 location = 5; } `; // Create a dummy proto file for parsing demonstration const tempDir = resolve(__dirname, './temp-proto-output'); mkdirSync(tempDir, { recursive: true }); const tempProtoFile = resolve(tempDir, 'dummy.proto'); writeFileSync(tempProtoFile, protoContent); async function generatePgProtoTypes() { try { // In a real application, 'inFile' would point to the libpg_query proto definitions. // For this example, we use our dummy proto file. const parser = new PgProtoParser(tempProtoFile, { outDir: tempDir, enums: { enumMap: { enabled: true, format: 'ts', toIntOutFile: 'enum-to-int.ts', toStrOutFile: 'enum-to-str.ts' } } }); await parser.write(); console.log(`Successfully generated types and utilities in: ${tempDir}`); console.log('Check files like types.ts, enums.ts, utils.ts in the output directory.'); // Example of importing a generated type (after generation) // const { A_Const } = await import(resolve(tempDir, 'types.ts')); // const myConst: A_Const = { node: { location: 0 }, ival: '123' }; // Example usage } catch (error) { console.error('Error generating types:', error); } } generatePgProtoTypes();
Debug
Known issues
gotchaThis package (`pg-proto-parser`) is designed to parse PostgreSQL *Protocol Buffer definitions* (specifically for the AST generated by `libpg_query`), not raw SQL statements or the PostgreSQL wire protocol. Developers often confuse it with other `pg-` related parsing libraries like `pgsql-parser` (for SQL) or `pg-protocol` (for wire protocol), leading to incorrect usage. Ensure you need to process `.proto` files defining PostgreSQL internal structures.
fix
Verify that your use case specifically involves working with the protobuf schemas that define PostgreSQL's AST or internal messages. If you need to parse SQL, consider `@pgsql/parser` or `pgsql-parser`. If you need to interact with the PostgreSQL wire protocol, `pg-protocol` is the appropriate library.
affects: >=1.0.0
breakingChanges in the underlying PostgreSQL protobuf schema (e.g., `libpg_query` protobuf definitions) can lead to breaking changes in the generated TypeScript types, interfaces, and utilities. Field renumbering, type changes, or removal of fields within the `.proto` files directly impact the output of `pg-proto-parser`, requiring updates to any code consuming these generated artifacts.
fix
Regularly regenerate your types and utilities with `pg-proto-parser` after updating the source PostgreSQL protobuf definitions. Implement robust versioning and compatibility checks for your generated code consumers, as per standard Protocol Buffers schema evolution best practices. Consider using tools like `proto-break` to detect breaking changes in `.proto` files before deployment.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'pg-proto-parser' or its corresponding type declarations.
This error typically indicates an issue with module resolution, either due to incorrect package installation, wrong import paths, or a CommonJS/ESM conflict.
fix
Ensure the package is installed (`npm install pg-proto-parser` or `yarn add pg-proto-parser`). If using ESM `import` syntax in a CommonJS project, ensure your `package.json` has `"type": "module"` or use a bundler. For TypeScript, check `tsconfig.json` for `moduleResolution` and `target` settings, and confirm the package's type declarations are correctly linked.
Error: The 'root' or 'inFile' option must be provided to the PgProtoParser constructor.
The `PgProtoParser` constructor requires a source for the protobuf definitions, either a protobuf `Root` object or a path to a `.proto` file, along with an `outDir` for generated files.
fix
When initializing `PgProtoParser`, pass a valid path to your primary `.proto` file as the first argument, and an options object containing at least `outDir` where the generated files should be placed. For example: `new PgProtoParser('path/to/your.proto', { outDir: './generated' });`
Upgrade
Version history
1.30.5latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
pg-proto-parser — npm install pg-proto-parser · libregistry