feat(pgsql-types): add new package for narrowed PostgreSQL AST types

This package generates narrowed TypeScript type definitions for PostgreSQL
AST Node fields by parsing SQL fixtures and inferring which specific node
types actually appear in each Node-typed field.

Features:
- Inference script that parses all SQL fixtures from kitchen-sink and postgres directories
- Generates field-metadata.json with inferred type information
- Generates narrowed TypeScript types with wrapped unions like { Integer: Integer } | { Float: Float }
- Type aliases for each Node-typed field to avoid bloating interfaces

Example: DefElem.arg is now typed as DefElem_arg which is a union of
{ A_Const: A_Const } | { Boolean: Boolean } | { Float: Float } | { Integer: Integer } | ...
instead of the generic Node type.

Addresses: constructive-io/libpg-query-node#143

Author: pyramation

packages/pgsql-types/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pgsql-types",
+  "version": "17.0.0",
+  "author": "Constructive <[email protected]>",
+  "description": "Narrowed PostgreSQL AST type definitions with specific Node unions",
+  "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 infer && 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",
+    "infer": "ts-node scripts/infer-field-metadata.ts",
+    "generate": "ts-node scripts/generate-types.ts",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "devDependencies": {
+    "makage": "^0.1.8",
+    "libpg-query": "17.7.3"
+  },
+  "dependencies": {
+    "@pgsql/types": "^17.6.2",
+    "@pgsql/enums": "^17.6.2",
+    "@pgsql/utils": "^17.8.9"
+  },
+  "keywords": [
+    "sql",
+    "postgres",
+    "postgresql",
+    "pg",
+    "ast",
+    "types",
+    "typescript"
+  ]
+}

packages/pgsql-types/scripts/generate-types.ts

@@ -0,0 +1,182 @@
+import { runtimeSchema, NodeSpec, FieldSpec } from '../../utils/src/runtime-schema';
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface FieldMetadata {
+  nullable: boolean;
+  tags: string[];
+  isArray: boolean;
+}
+
+interface NodeFieldMetadata {
+  [fieldName: string]: FieldMetadata;
+}
+
+interface AllFieldMetadata {
+  [nodeName: string]: NodeFieldMetadata;
+}
+
+const schemaMap = new Map<string, NodeSpec>(
+  runtimeSchema.map((spec: NodeSpec) => [spec.name, spec])
+);
+
+const primitiveTypeMap: Record<string, string> = {
+  'string': 'string',
+  'bool': 'boolean',
+  'int32': 'number',
+  'int64': 'number',
+  'uint32': 'number',
+  'uint64': 'number',
+  'float': 'number',
+  'double': 'number',
+  'bytes': 'Uint8Array',
+};
+
+function isPrimitiveType(type: string): boolean {
+  return type in primitiveTypeMap;
+}
+
+function getTsType(type: string): string {
+  return primitiveTypeMap[type] || type;
+}
+
+function generateWrappedUnion(tags: string[]): string {
+  if (tags.length === 0) {
+    return 'Node';
+  }
+  
+  const sortedTags = [...tags].sort();
+  return sortedTags.map(tag => `{ ${tag}: ${tag} }`).join(' | ');
+}
+
+function generateTypeAlias(nodeName: string, fieldName: string, tags: string[]): string {
+  const aliasName = `${nodeName}_${fieldName}`;
+  const union = generateWrappedUnion(tags);
+  return `export type ${aliasName} = ${union};`;
+}
+
+function generateInterface(
+  nodeSpec: NodeSpec,
+  fieldMetadata: NodeFieldMetadata | undefined
+): string {
+  const lines: string[] = [];
+  lines.push(`export interface ${nodeSpec.name} {`);
+  
+  for (const field of nodeSpec.fields) {
+    const tsType = getFieldType(nodeSpec.name, field, fieldMetadata);
+    const optional = field.optional ? '?' : '';
+    lines.push(`  ${field.name}${optional}: ${tsType};`);
+  }
+  
+  lines.push('}');
+  return lines.join('\n');
+}
+
+function getFieldType(
+  nodeName: string,
+  field: FieldSpec,
+  fieldMetadata: NodeFieldMetadata | undefined
+): string {
+  let baseType: string;
+  
+  if (field.type === 'Node') {
+    const meta = fieldMetadata?.[field.name];
+    if (meta && meta.tags.length > 0) {
+      baseType = `${nodeName}_${field.name}`;
+    } else {
+      baseType = 'Node';
+    }
+  } else if (isPrimitiveType(field.type)) {
+    baseType = getTsType(field.type);
+  } else {
+    if (schemaMap.has(field.type)) {
+      baseType = `{ ${field.type}: ${field.type} }`;
+    } else {
+      baseType = field.type;
+    }
+  }
+  
+  if (field.isArray) {
+    if (baseType.includes('|') || baseType.includes('{')) {
+      return `(${baseType})[]`;
+    }
+    return `${baseType}[]`;
+  }
+  
+  return baseType;
+}
+
+function generateTypes(metadata: AllFieldMetadata): string {
+  const lines: string[] = [];
+  
+  lines.push('/**');
+  lines.push(' * This file was automatically generated by pgsql-types.');
+  lines.push(' * DO NOT MODIFY IT BY HAND.');
+  lines.push(' * ');
+  lines.push(' * These types provide narrowed Node unions based on actual usage');
+  lines.push(' * patterns discovered by parsing SQL fixtures.');
+  lines.push(' */');
+  lines.push('');
+  
+  lines.push("import type { Node } from '@pgsql/types';");
+  lines.push("export type { Node } from '@pgsql/types';");
+  lines.push("export * from '@pgsql/enums';");
+  lines.push('');
+  
+  const typeAliases: string[] = [];
+  for (const nodeName of Object.keys(metadata).sort()) {
+    const nodeMetadata = metadata[nodeName];
+    for (const fieldName of Object.keys(nodeMetadata).sort()) {
+      const fieldMeta = nodeMetadata[fieldName];
+      if (fieldMeta.tags.length > 0) {
+        typeAliases.push(generateTypeAlias(nodeName, fieldName, fieldMeta.tags));
+      }
+    }
+  }
+  
+  if (typeAliases.length > 0) {
+    lines.push('// Narrowed type aliases for Node-typed fields');
+    lines.push(typeAliases.join('\n'));
+    lines.push('');
+  }
+  
+  lines.push('// Interfaces with narrowed Node types');
+  for (const nodeSpec of runtimeSchema) {
+    const nodeMetadata = metadata[nodeSpec.name];
+    lines.push(generateInterface(nodeSpec, nodeMetadata));
+    lines.push('');
+  }
+  
+  return lines.join('\n');
+}
+
+async function main() {
+  const metadataPath = path.resolve(__dirname, '../src/field-metadata.json');
+  const outputPath = path.resolve(__dirname, '../src/types.ts');
+  
+  if (!fs.existsSync(metadataPath)) {
+    console.error('Field metadata not found. Run "npm run infer" first.');
+    process.exit(1);
+  }
+  
+  const metadata: AllFieldMetadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+  
+  console.log('Generating narrowed types...');
+  const typesContent = generateTypes(metadata);
+  
+  fs.writeFileSync(outputPath, typesContent);
+  console.log(`Wrote narrowed types to ${outputPath}`);
+  
+  let totalAliases = 0;
+  for (const nodeName of Object.keys(metadata)) {
+    for (const fieldName of Object.keys(metadata[nodeName])) {
+      if (metadata[nodeName][fieldName].tags.length > 0) {
+        totalAliases++;
+      }
+    }
+  }
+  
+  console.log(`Generated ${totalAliases} narrowed type aliases`);
+}
+
+main().catch(console.error);