@pgsql/utils 13.9.0 → 13.10.1

package/README.md

@@ -16,6 +16,22 @@
 
 `@pgsql/utils` is a companion utility library for `@pgsql/types`, offering convenient functions to work with PostgreSQL Abstract Syntax Tree (AST) nodes and enums in a type-safe manner. This library facilitates the creation of AST nodes and simplifies the process of converting between enum names and their respective integer values, as defined in the PostgreSQL parser output.
 
+# Table of Contents
+
+1. [@pgsql/utils](#pgsql-utils)
+   - [Features](#features)
+2. [Installation](#installation)
+3. [Usage](#usage)
+   - [AST Node Creation](#ast-node-creation)
+     - [JSON AST](#json-ast)
+     - [Select Statement](#select-statement)
+     - [Creating Table Schemas Dynamically](#creating-table-schemas-dynamically)
+   - [Enum Value Conversion](#enum-value-conversion)
+     - [Example 1: Converting Enum Name to Integer](#example-1-converting-enum-name-to-integer)
+     - [Example 2: Converting Integer to Enum Name](#example-2-converting-integer-to-enum-name)
+4. [Related Projects](#related)
+5. [Disclaimer](#disclaimer)
+
 ## Features
 
 - **AST Node Creation**: Simplifies the process of constructing PostgreSQL AST nodes, allowing for easy assembly of SQL queries or statements programmatically.
@@ -38,25 +54,129 @@ npm install @pgsql/utils
 
 With the AST helper methods, creating complex SQL ASTs becomes straightforward and intuitive.
 
+#### JSON AST
+
+Explore the PostgreSQL Abstract Syntax Tree (AST) as JSON objects with ease using `@pgsql/utils`. Below is an example of how you can generate a JSON AST using TypeScript:
+
+```ts
+import ast from '@pgsql/utils';
+const selectStmt = ast.selectStmt({
+  targetList: [
+    ast.resTarget({
+      val: ast.columnRef({
+        fields: [ast.aStar()]
+      })
+    })
+  ],
+  fromClause: [
+    ast.rangeVar({
+      relname: 'some_amazing_table',
+      inh: true,
+      relpersistence: 'p'
+    })
+  ],
+  limitOption: 'LIMIT_OPTION_DEFAULT',
+  op: 'SETOP_NONE'
+});
+console.log(selectStmt);
+// Output: { "SelectStmt": { "targetList": [ { "ResTarget": { "val": { "ColumnRef": { "fields": [ { "A_Star": {} } ] } } } } ], "fromClause": [ { "RangeVar": { "relname": "some_amazing_table", "inh": true, "relpersistence": "p" } } ], "limitOption": "LIMIT_OPTION_DEFAULT", "op": "SETOP_NONE" } }
+```
+
+#### Select Statement
+
 ```ts
 import ast, { CreateStmt, ColumnDef } from '@pgsql/utils';
 import { deparse } from 'pgsql-deparser';
 
-const newColumn: ColumnDef = ast.columnDef({
-    colname: 'id',
-    typeName: ast.typeName({
-        names: [ast.string({ str: 'int4' })]
+const selectStmt: SelectStmt = ast.selectStmt({
+  targetList: [
+    ast.resTarget({
+      val: ast.columnRef({
+        fields: [ast.aStar()]
+      })
     })
+  ],
+  fromClause: [
+    ast.rangeVar({
+      schemaname: 'myschema',
+      relname: 'mytable',
+      inh: true,
+      relpersistence: 'p'
+    })
+  ],
+  whereClause: ast.aExpr({
+    kind: 'AEXPR_OP',
+    name: [ast.string({ str: '=' })],
+    lexpr: ast.columnRef({
+      fields: [ast.string({ str: 'a' })]
+    }),
+    rexpr: ast.typeCast({
+      arg: ast.aConst({
+        val: ast.string({ str: 't' })
+      }),
+      typeName: ast.typeName({
+        names: [
+          ast.string({ str: 'pg_catalog' }),
+          ast.string({ str: 'bool' })
+        ],
+        typemod: -1
+      })
+    })
+  }),
+  limitOption: 'LIMIT_OPTION_DEFAULT',
+  op: 'SETOP_NONE'
 });
 
-const createStmt: CreateStmt = ast.createStmt({
-    relation: ast.rangeVar({
-        relname: 'new_table'
+deparse(createStmt, {});
+// SELECT * FROM myschema.mytable WHERE a = TRUE
+```
+
+#### Creating Table Schemas Dynamically
+
+```ts
+// Example JSON schema
+const schema = {
+  "tableName": "users",
+  "columns": [
+    { "name": "id", "type": "int", "constraints": ["PRIMARY KEY"] },
+    { "name": "username", "type": "string" },
+    { "name": "email", "type": "string", "constraints": ["UNIQUE"] },
+    { "name": "created_at", "type": "timestamp", "constraints": ["NOT NULL"] }
+  ]
+};
+
+// Construct the CREATE TABLE statement
+const createStmt = ast.createStmt({
+  relation: ast.rangeVar({ 
+    relname: schema.tableName,
+    inh: true,
+    relpersistence: 'p'
+  }).RangeVar as RangeVar, // special case due to PG AST
+  tableElts: schema.columns.map(column => ast.columnDef({
+    colname: column.name,
+    typeName: ast.typeName({
+      names: [ast.string({ str: column.type })]
     }),
-    tableElts: [newColumn]
+    constraints: column.constraints?.map(constraint =>
+      ast.constraint({
+        contype: constraint === "PRIMARY KEY" ? "CONSTR_PRIMARY" : constraint === "UNIQUE" ? "CONSTR_UNIQUE" : "CONSTR_NOTNULL"
+      })
+    )
+  }))
 });
 
-deparse(createStmt, {}) // SQL!
+// `deparse` function converts AST to SQL string
+const sql = deparse(createStmt, {});
+
+console.log(sql);
+// OUTPUT: 
+
+// CREATE TABLE users (
+//  id int PRIMARY KEY,
+// 	username text,
+// 	email text UNIQUE,
+// 	created_at timestamp NOT NULL 
+// )
 ```
 
 ### Enum Value Conversion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgsql/utils",
-  "version": "13.9.0",
+  "version": "13.10.1",
   "description": "PostgreSQL AST utils for pgsql-parser",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "homepage": "https://github.com/launchql/pgsql-parser",
@@ -66,7 +66,7 @@
     "esprima": "4.0.1",
     "jest": "^29.5.0",
     "pg-proto-parser": "^1.20.0",
-    "pgsql-deparser": "^13.13.0",
+    "pgsql-deparser": "^13.14.0",
     "prettier": "^2.8.7",
     "rimraf": "5.0.5",
     "ts-jest": "^29.1.0",
@@ -77,5 +77,5 @@
     "@pgsql/types": "^13.8.0",
     "nested-obj": "0.0.1"
   },
-  "gitHead": "112e54189b4b47ff1080d497704de8c4e94a4743"
+  "gitHead": "a4751a2635eaa353e45b0f8832ac77e80b2f114a"
 }