docs(pgsql-types): add README with experimental warning and DefElem example

Author: pyramation

packages/pgsql-types/README.md

@@ -0,0 +1,126 @@
+# pgsql-types
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/pgsql-parser/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/pgsql-parser/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/pgsql-parser/blob/main/LICENSE-MIT"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/pgsql-types"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/pgsql-parser?filename=packages%2Fpgsql-types%2Fpackage.json"/></a>
+</p>
+
+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`](https://www.npmjs.com/package/@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
+
+```bash
+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:
+
+```typescript
+// @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:
+
+```typescript
+// 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
+
+```typescript
+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`](https://www.npmjs.com/package/@pgsql/types) - Production TypeScript types for PostgreSQL AST
+- [`@pgsql/enums`](https://www.npmjs.com/package/@pgsql/enums) - PostgreSQL enum definitions
+- [`pgsql-parser`](https://www.npmjs.com/package/pgsql-parser) - Parse SQL to AST
+- [`pgsql-deparser`](https://www.npmjs.com/package/pgsql-deparser) - Convert AST back to SQL
+
+## License
+
+MIT