readmes

Author: pyramation

README.md

@@ -1,9 +1,10 @@
-# PostgreSQL AST Tools
+# pgsql-parser 
 
 <p align="center" width="100%">
   <img height="120" src="https://github.com/launchql/pgsql-parser/assets/545047/6440fa7d-918b-4a3b-8d1b-755d85de8bea" />
 </p>
 
+
 <p align="center" width="100%">
   <a href="https://github.com/launchql/pgsql-parser/actions/workflows/run-tests.yaml">
     <img height="20" src="https://github.com/launchql/pgsql-parser/actions/workflows/run-tests.yaml/badge.svg" />
@@ -13,6 +14,9 @@
    <a href="https://github.com/launchql/pgsql-parser/blob/main/LICENSE-MIT"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
 </p>
 
+## PostgreSQL AST Tools
+
+
 A comprehensive monorepo for PostgreSQL Abstract Syntax Tree (AST) parsing, manipulation, and code generation. This collection of packages provides everything you need to work with PostgreSQL at the AST level, from parsing SQL queries to generating type-safe TypeScript definitions.
 
 ## 📦 Packages Overview
@@ -56,6 +60,7 @@ import { parse } from 'pgsql-parser';
 
 const ast = await parse('SELECT * FROM users WHERE id = 1');
 console.log(JSON.stringify(ast, null, 2));
+// {"version":170004,"stmts":[{"stmt":{"SelectStmt":{"targetList":[{"ResTarget": ... ,"op":"SETOP_NONE"}}}]}
 ```
 
 #### Convert AST back to SQL
@@ -68,19 +73,20 @@ console.log(sql); // SELECT * FROM users WHERE id = 1
 
 #### Build AST Programmatically
 ```typescript
-import ast from '@pgsql/utils';
+import * as t from '@pgsql/utils';
+import { RangeVar, SelectStmt } from '@pgsql/types';
 
-const selectStmt = ast.selectStmt({
+const stmt: { SelectStmt: SelectStmt } = t.nodes.selectStmt({
   targetList: [
-    ast.resTarget({
-      val: ast.columnRef({
-        fields: [ast.aStar()]
+    t.nodes.resTarget({
+      val: t.nodes.columnRef({
+        fields: [t.nodes.aStar()]
       })
     })
   ],
   fromClause: [
-    ast.rangeVar({
-      relname: 'users',
+    t.nodes.rangeVar({
+      relname: 'some_table',
       inh: true,
       relpersistence: 'p'
     })
@@ -102,22 +108,6 @@ pgsql deparse ast.json
 pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums
 ```
 
-## 🏗️ Architecture
-
-This monorepo is organized to provide modular, focused tools that work together seamlessly:
-
-```
-pgsql-parser/
-├── packages/
-│   ├── parser/          # Core parser with WebAssembly
-│   ├── deparser/        # Pure TypeScript deparser
-│   ├── pgsql-cli/       # Unified CLI tool
-│   ├── utils/           # AST construction utilities
-│   ├── proto-parser/    # Protobuf code generation
-│   └── transform/       # (Not production-ready yet)
-└── ...
-```
-
 ### Package Relationships
 
 - **pgsql-parser** provides full parsing and deparsing capabilities using the actual PostgreSQL parser
@@ -148,28 +138,20 @@ cd packages/parser
 npm run build
 ```
 
-## 📚 Documentation
+## Documentation
 
 Each package has its own detailed README:
 
-- [pgsql-parser Documentation](./packages/parser/README.md)
-- [pgsql-deparser Documentation](./packages/deparser/README.md)
-- [@pgsql/cli Documentation](./packages/pgsql-cli/README.md)
-- [@pgsql/utils Documentation](./packages/utils/README.md)
-- [pg-proto-parser Documentation](./packages/proto-parser/README.md)
+- [`pgsql-parser`](./packages/parser/README.md)
+- [`pgsql-deparser`](./packages/deparser/README.md)
+- [`@pgsql/cli`](./packages/pgsql-cli/README.md)
+- [`@pgsql/utils`](./packages/utils/README.md)
+- [`pg-proto-parser`](./packages/proto-parser/README.md)
 
-## 🎯 Use Cases
-
-- **SQL Query Analysis**: Parse queries to understand their structure and components
-- **Query Transformation**: Modify queries programmatically at the AST level
-- **SQL Generation**: Build complex queries programmatically with type safety
-- **Code Generation**: Generate TypeScript types from PostgreSQL schemas
-- **Query Validation**: Validate SQL syntax using the real PostgreSQL parser
-- **Database Tooling**: Build developer tools that understand PostgreSQL deeply
-
-## 💡 Examples
+## Examples
 
 ### Transform a Query
+
 ```typescript
 import { parse } from 'pgsql-parser';
 import { deparse } from 'pgsql-deparser';
@@ -186,38 +168,39 @@ console.log(newSql); // SELECT * FROM customers WHERE active = TRUE
 ```
 
 ### Build a Query Programmatically
+
 ```typescript
 import ast from '@pgsql/utils';
-import { deparse } from 'pgsql-deparser';
+import { deparse as deparseSync } from 'pgsql-deparser';
 
-const query = ast.selectStmt({
+const query: { SelectStmt: SelectStmt } = t.nodes.selectStmt({
   targetList: [
-    ast.resTarget({
-      val: ast.columnRef({
-        fields: [ast.string({ str: 'name' })]
+    t.nodes.resTarget({
+      val: t.nodes.columnRef({
+        fields: [t.nodes.string({ sval: 'name' })]
       })
     }),
-    ast.resTarget({
-      val: ast.columnRef({
-        fields: [ast.string({ str: 'email' })]
+    t.nodes.resTarget({
+      val: t.nodes.columnRef({
+        fields: [t.nodes.string({ sval: 'email' })]
       })
     })
   ],
   fromClause: [
-    ast.rangeVar({
+    t.nodes.rangeVar({
       relname: 'users',
       inh: true,
       relpersistence: 'p'
     })
   ],
-  whereClause: ast.aExpr({
+  whereClause: t.nodes.aExpr({
     kind: 'AEXPR_OP',
-    name: [ast.string({ str: '>' })],
-    lexpr: ast.columnRef({
-      fields: [ast.string({ str: 'age' })]
+    name: [t.nodes.string({ sval: '>' })],
+    lexpr: t.nodes.columnRef({
+      fields: [t.nodes.string({ sval: 'age' })]
     }),
-    rexpr: ast.aConst({
-      val: ast.integer({ ival: 18 })
+    rexpr: t.nodes.aConst({
+      ival: t.ast.integer({ ival: 18 })
     })
   }),
   limitOption: 'LIMIT_OPTION_DEFAULT',
@@ -228,46 +211,17 @@ console.log(deparse(query));
 // SELECT name, email FROM users WHERE age > 18
 ```
 
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-### Development Workflow
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE-MIT) file for details.
-
-## 🙏 Credits
-
-Built on the excellent work of several contributors:
-
-* **[Dan Lynch](https://github.com/pyramation)** — official maintainer since 2018 and architect of the current implementation
-* **[Lukas Fittl](https://github.com/lfittl)** for [libpg_query](https://github.com/pganalyze/libpg_query) — the core PostgreSQL parser that powers this project
-* **[Greg Richardson](https://github.com/gregnr)** for AST guidance and pushing the transition to WASM for better interoperability
-* **[Ethan Resnick](https://github.com/ethanresnick)** for the original Node.js N-API bindings
-* **[Zac McCormick](https://github.com/zhm)** for the foundational [node-pg-query-native](https://github.com/zhm/node-pg-query-native) parser
-
-## 🔗 Related Projects
-
-### Core Packages (in this monorepo)
-* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js
-* [pgsql-deparser](https://www.npmjs.com/package/pgsql-deparser): Lightning-fast SQL generation from AST
-* [@pgsql/cli](https://www.npmjs.com/package/@pgsql/cli): Unified CLI for PostgreSQL AST operations
-* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): Type-safe AST construction utilities
-* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): PostgreSQL protobuf parser and code generator
-
-
+## Related
 
-### External Dependencies
-* [libpg-query](https://github.com/launchql/libpg-query-node): The PostgreSQL parser exposed for Node.js
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
+* [pgsql-deparser](https://www.npmjs.com/package/pgsql-deparser): A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement `pgsql-parser`.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
+* [@pgsql/utils](https://www.npmjs.com/package/@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.
+* [pg-proto-parser](https://www.npmjs.com/package/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](https://github.com/launchql/libpg-query-node): The real PostgreSQL parser exposed for Node.js, used primarily in `pgsql-parser` for parsing and deparsing SQL queries.
 
-## ⚖️ Disclaimer
+## Disclaimer
 
 AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.