pgsql-types

Narrowed TypeScript type definitions for PostgreSQL AST nodes.

Experimental: This package provides narrowed types inferred from real SQL usage patterns. For production use, see @pgsql/types. However, please kick the tires and let us know what you think!

Overview

This package provides TypeScript type definitions for PostgreSQL AST nodes with narrowed Node unions. Instead of generic Node types that could be any of ~250 node types, fields are narrowed to only the specific types that actually appear in practice.

The narrowed types are inferred by parsing thousands of SQL statements from PostgreSQL's test suite and tracking which node types appear in each field.

Installation

npm install pgsql-types

The Problem

With @pgsql/types, the arg field in DefElem is typed as Node - a union of all possible AST node types:

// @pgsql/types
export interface DefElem {
  defnamespace?: string;
  defname?: string;
  arg?: Node;  // Could be any of ~250 types!
  defaction?: DefElemAction;
  location?: number;
}

When processing the AST, you have no guidance on what types to actually handle.

The Solution

With pgsql-types, the same field is narrowed to only the types that actually appear:

// pgsql-types
export interface DefElem {
  defnamespace?: string;
  defname?: string;
  arg?: { A_Const: A_Const }
      | { A_Star: A_Star }
      | { Boolean: Boolean }
      | { Float: Float }
      | { Integer: Integer }
      | { List: List }
      | { String: String }
      | { TypeName: TypeName }
      | { VariableSetStmt: VariableSetStmt };
  defaction?: DefElemAction;
  location?: number;
}

Now you know exactly which cases to handle when processing DefElem.arg.

Usage

import { DefElem, SelectStmt, CreateStmt } from 'pgsql-types';

function processDefElem(elem: DefElem) {
  if (elem.arg) {
    // TypeScript knows arg can only be one of 9 specific types
    if ('String' in elem.arg) {
      console.log('String value:', elem.arg.String.sval);
    } else if ('Integer' in elem.arg) {
      console.log('Integer value:', elem.arg.Integer.ival);
    } else if ('List' in elem.arg) {
      console.log('List with', elem.arg.List.items?.length, 'items');
    }
    // ... handle other cases
  }
}

How It Works

The narrowed types are generated by:

1. Parsing all SQL fixtures from PostgreSQL's regression test suite (~70,000 statements)
2. Walking each AST and tracking which node types appear in each Node-typed field
3. Generating TypeScript interfaces with narrowed unions based on the observed types

This approach ensures the narrowed types reflect real-world usage patterns from PostgreSQL's own test suite.

Exports

This package exports:

• All narrowed interfaces (e.g., SelectStmt, CreateStmt, DefElem, etc.)
• The Node type from @pgsql/types
• All enums from @pgsql/enums

Limitations

• The narrowed types are based on SQL fixtures and may not cover every possible valid AST structure
• Some rarely-used node combinations may not be included in the narrowed unions
• For maximum type safety in production, consider using @pgsql/types with runtime validation

Related Packages

• @pgsql/types - Production TypeScript types for PostgreSQL AST
• @pgsql/enums - PostgreSQL enum definitions
• pgsql-parser - Parse SQL to AST
• pgsql-deparser - Convert AST back to SQL

License

MIT

🛠 Built by the Constructive team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on GitHub.

Related

• pgpm: A Postgres Package Manager that brings modular development to PostgreSQL with reusable packages, deterministic migrations, recursive dependency resolution, and tag-aware versioning.
• 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: PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
• pgsql-parser: The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
• 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: Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
• @pgsql/types: Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
• @pgsql/enums: Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
• @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: 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: A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
• libpg-query: 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.