Javascript: Add typescript generation + adjust jsdoc typing

Author: surister

cratedb_sqlparse_js/cratedb_sqlparse/AstBuilder.js

@@ -1,11 +1,12 @@
 import SqlBaseParserVisitor from "./generated_parser/SqlBaseParserVisitor.js";
+import SqlBaseParser from "./generated_parser/SqlBaseParser.js";
 import {Statement} from "./parser.js"
 import {Table} from "./models.js"
 
 
 /**
  *
- * @param {String} text
+ * @param {string} text
  * @returns {Boolean}
  */
 function isDigit(text) {
@@ -26,7 +27,7 @@ export class AstBuilder extends SqlBaseParserVisitor {
     /**
      *
      * @param {Object} node
-     * @returns {(String|null)}
+     * @returns {(string|null)}
      */
     getText(node) {
         if (node) {

cratedb_sqlparse_js/cratedb_sqlparse/models.js

@@ -5,26 +5,22 @@
 export class Metadata {
 
     /**
-     *
-     * @param {Table[]} tables
-     * @param parameterizedProperties
-     * @param withProperties
+     * @param {Table[]} tables - The referenced tables in the query.
+     * @param {object} parameterizedProperties - The properties whose value can be used to inject parameters, they start with '$', example: `CREATE TABLE a (b text) WITH ("allocation.max_retries" = $1)`
+     * @param {object} withProperties - SQL properties, defined after a `WITH` statement. Example: `CREATE TABLE a (b text) WITH ("allocation.max_retries" = 5)`
      */
     constructor(tables, parameterizedProperties, withProperties) {
         this.tables = tables || []
         this.parameterizedProperties = parameterizedProperties || {}
         this.withProperties = withProperties || {}
     }
-
-    toString() {
-
-    }
 }
 
 /**
  *
- * @param {String} text
- * @param {String} quoted_with
+ * @param {string} text
+ * @param {string} quoted_with
+ * @return {string}
  */
 function quoted(text, quoted_with = '"') {
     return quoted_with + text + quoted_with
@@ -33,8 +29,9 @@ function quoted(text, quoted_with = '"') {
 export class Table {
     /**
      *
-     * @param {String} name
-     * @param {String} schema
+     * @param {string} name
+     * @param {string} schema
+     * @property {string} fqn - Full qualified name, example: "sys"."shards"
      */
     constructor(name, schema) {
         this.name = name
@@ -43,7 +40,7 @@ export class Table {
     }
 
     /**
-     * @return {String} The full qualified name, quoted.
+     * @return {string} - The full qualified name, quoted.
      */
     _getFqn() {
         return (this.schema ? quoted(this.schema) + "." : "") + quoted(this.name)

cratedb_sqlparse_js/cratedb_sqlparse/parser.js

@@ -31,12 +31,12 @@ export class ParseError extends Error {
 
     /**
      *
-     * @param {String} query
-     * @param {String} msg
-     * @param offending_token
-     * @param e
-     * @member {String} errorMessage
-     * @member {String} errorMessageVerbose
+     * @param {string} query
+     * @param {string} msg
+     * @param {object} offending_token
+     * @param {object} e
+     * @member {string} errorMessage
+     * @member {string} errorMessageVerbose
      */
     constructor(query, msg, offending_token, e) {
         super(msg);
@@ -53,14 +53,26 @@ export class ParseError extends Error {
         return `[line ${this.line}:${this.column} ${this.message}]`
     }
 
+    /**
+     *
+     * @returns {Number}
+     */
     getColumn() {
         return this.offendingToken.column
     }
 
+    /**
+     *
+     * @returns {Number}
+     */
     getLine() {
         return this.offendingToken.line
     }
 
+    /**
+     *
+     * @returns {string}
+     */
     getOriginalQueryWithErrorMarked() {
         const query = this.offendingToken.source[1].strdata
         const offendingTokenText = query.substring(this.offendingToken.start, this.offendingToken.stop + 1)
@@ -133,12 +145,12 @@ export class Statement {
 
     /**
      *
-     * @property {String} query
-     * @property {String} originalQuery
-     * @property {Metadata} metadata
-     * @property {String} type
-     * @property {String} tree
-     * @param {Object} ctx
+     * @member {Statement} query
+     * @member {string} originalQuery
+     * @member {Metadata} metadata
+     * @member {string} type - The type of query, example: 'SELECT'
+     * @member {string} tree
+     * @param {object} ctx
      * @param {ParseError} exception
      */
     constructor(ctx, exception) {
@@ -159,8 +171,8 @@ export class Statement {
 
 /**
  *
- * @param {String} string
- * @returns {String}
+ * @param {string} string
+ * @returns {string}
  */
 function trim(string) {
     return string.replace(/^\s+|\s+$/gm, '');
@@ -187,7 +199,7 @@ function findSuitableError(statement, errors) {
 
 /**
  *
- * @param {String} query
+ * @param {string} query
  * @param {Boolean} raise_exception
  * @returns {Statement[]}
  */

cratedb_sqlparse_js/package.json

@@ -32,6 +32,7 @@
   ],
   "main": "./dist/sqlparse.umd.cjs",
   "module": "./dist/sqlparse.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/sqlparse.js",
@@ -42,11 +43,14 @@
     "antlr4": "^4.13.1-patch-1"
   },
   "devDependencies": {
+    "jsdoc": "^4.0.3",
+    "terser": "^5.31.1",
     "vite": "^5.3.2",
     "vitest": "^1.6.0"
   },
   "scripts": {
     "test": "vitest run",
-    "build": "vite build"
+    "build": "vite build && tsc",
+    "docs": "jsdoc *"
   }
 }

cratedb_sqlparse_js/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "include": ["cratedb_sqlparse/**/*"],
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist",
+    "declarationMap": true,
+  }
+}

cratedb_sqlparse_js/vite.config.js

@@ -9,6 +9,7 @@ import packageJson from './package.json';
 
 export default defineConfig({
     build: {
+        minify: "terser",
         lib: {
             // Could also be a dictionary or array of multiple entry points
             entry: resolve(__dirname, 'cratedb_sqlparse/index.js'),
@@ -17,7 +18,8 @@ export default defineConfig({
         }, rollupOptions: {
             // make sure to externalize deps that shouldn't be bundled
             // into your library
-            external: [], output: {},
+            external: [],
+            output: {},
         },
     },
 })