add JSON AST in docs

Author: pyramation

packages/utils/README.md

@@ -23,6 +23,7 @@
 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)
@@ -53,6 +54,34 @@ 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
@@ -105,7 +134,7 @@ deparse(createStmt, {});
 #### Creating Table Schemas Dynamically
 
 ```ts
-// Example JSON with schema
+// Example JSON schema
 const schema = {
   "tableName": "users",
   "columns": [
@@ -118,31 +147,36 @@ const schema = {
 
 // Construct the CREATE TABLE statement
 const createStmt = ast.createStmt({
-  relation: ast.rangeVar({ relname: schema.tableName }),
+  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 })]
     }),
     constraints: column.constraints?.map(constraint =>
       ast.constraint({
-        contype: constraint === "PRIMARY KEY" ? "CONSTR_PRIMARY" : constraint === "UNIQUE" ? "CONSTR_UNIQUE" : "CONSTR_NOTNULL",
-        keys: [ast.string({ str: column.name })]
+        contype: constraint === "PRIMARY KEY" ? "CONSTR_PRIMARY" : constraint === "UNIQUE" ? "CONSTR_UNIQUE" : "CONSTR_NOTNULL"
       })
     )
   }))
 });
 
-// Assuming `deparse` function converts AST to SQL string
+// `deparse` function converts AST to SQL string
 const sql = deparse(createStmt, {});
+
 console.log(sql);
-//  CREATE TABLE  (
-//  	id int PRIMARY KEY ( id ),
-// 	  username string,
-// 	  email string UNIQUE ( email ),
-// 	  created_at timestamp NOT NULL ( created_at ) 
-// )
+// OUTPUT: 
 
+// CREATE TABLE users (
+//  id int PRIMARY KEY,
+// 	username text,
+// 	email text UNIQUE,
+// 	created_at timestamp NOT NULL 
+// )
 ```
 
 ### Enum Value Conversion

packages/utils/__test__/__snapshots__/utils.test.ts.snap

@@ -1,11 +1,11 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`dynamic creation of tables 1`] = `
-"CREATE TABLE  (
- 	id int PRIMARY KEY ( id ),
-	username string,
-	email string UNIQUE ( email ),
-	created_at timestamp NOT NULL ( created_at ) 
+"CREATE TABLE users (
+ 	id int PRIMARY KEY,
+	username text,
+	email text UNIQUE,
+	created_at timestamp NOT NULL 
 )"
 `;
 

packages/utils/__test__/utils.test.ts

@@ -1,5 +1,5 @@
 import * as u from '../src';
-import ast, { SelectStmt } from '../src';
+import ast, { SelectStmt, RangeVar } from '../src';
 import { deparse } from 'pgsql-deparser';
 
 it('getEnumValue snapshots', () => {
@@ -83,30 +83,33 @@ it('dynamic creation of tables', () => {
     "tableName": "users",
     "columns": [
       { "name": "id", "type": "int", "constraints": ["PRIMARY KEY"] },
-      { "name": "username", "type": "string" },
-      { "name": "email", "type": "string", "constraints": ["UNIQUE"] },
+      { "name": "username", "type": "text" },
+      { "name": "email", "type": "text", "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 }),
+    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 })]
       }),
       constraints: column.constraints?.map(constraint =>
         ast.constraint({
-          contype: constraint === "PRIMARY KEY" ? "CONSTR_PRIMARY" : constraint === "UNIQUE" ? "CONSTR_UNIQUE" : "CONSTR_NOTNULL",
-          keys: [ast.string({ str: column.name })]
+          contype: constraint === "PRIMARY KEY" ? "CONSTR_PRIMARY" : constraint === "UNIQUE" ? "CONSTR_UNIQUE" : "CONSTR_NOTNULL"
         })
       )
     }))
   });
 
-  // Assuming `deparse` function converts AST to SQL string
+  // `deparse` function converts AST to SQL string
   const sql = deparse(createStmt, {});
   expect(sql).toMatchSnapshot();
 })