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!

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.

npm install pgsql-types

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.

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.

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
  }
}

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.

This package exports:

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

• 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

• @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

MIT