Refactor SQL parser API to use top-level functions

Author: guan404ming

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "sqlparser-rs-wasm"
-version = "0.60.3"
+version = "0.60.3-rc2"
 edition = "2021"
 description = "WebAssembly bindings for sqlparser-rs SQL parser"
 license = "Apache-2.0"

Cargo.toml

@@ -26,77 +26,116 @@ npm install sqlparser-rs
 ## Quick Start
 
 ```typescript
-import { Parser, GenericDialect, PostgreSqlDialect } from 'sqlparser-rs';
+import { parse, format, validate } from 'sqlparser-rs';
 
-// Simple parsing
-const statements = Parser.parse('SELECT * FROM users', new GenericDialect());
+// Simple parsing (uses generic dialect by default)
+const statements = parse('SELECT * FROM users');
 console.log(statements);
 
-// With specific dialect
-const pgStatements = Parser.parse(
-  'SELECT * FROM users WHERE id = $1',
-  new PostgreSqlDialect()
-);
+// With specific dialect (string name)
+const pgStatements = parse('SELECT * FROM users WHERE id = $1', 'postgresql');
 
 // Format SQL
-const formatted = Parser.format('select   *   from   users', new GenericDialect());
+const formatted = format('select   *   from   users');
 console.log(formatted); // "SELECT * FROM users"
 
 // Validate SQL
 try {
-  Parser.validate('SELEC * FROM users', new GenericDialect());
+  validate('SELEC * FROM users');
 } catch (error) {
   console.log('Invalid SQL:', error.message);
 }
 ```
 
 ## API
 
-### Parser
+### Top-Level Functions
 
-The main class for parsing SQL.
-
-#### Static Methods
+The simplest way to use the parser:
 
 ```typescript
-// Parse SQL into statements
-const statements = Parser.parse(sql: string, dialect: Dialect): Statement[];
-
-// Parse and return JSON string
-const json = Parser.parseToJson(sql: string, dialect: Dialect): string;
+import { parse, format, validate } from 'sqlparser-rs';
 
-// Parse and return formatted SQL string
-const formatted = Parser.parseToString(sql: string, dialect: Dialect): string;
+// Parse SQL - dialect defaults to 'generic'
+parse('SELECT * FROM users');
+parse('SELECT * FROM users', 'postgresql');
+parse('SELECT * FROM users', 'mysql');
 
 // Format SQL (round-trip through parser)
-const formatted = Parser.format(sql: string, dialect: Dialect): string;
+format('select * from users');  // "SELECT * FROM users"
+
+// Validate SQL syntax (throws ParserError if invalid)
+validate('SELECT * FROM users');  // true
+```
+
+### Dialect Options
 
-// Validate SQL syntax
-const isValid = Parser.validate(sql: string, dialect: Dialect): boolean;
+Dialects can be specified as strings or class instances:
 
-// Get list of supported dialects
-const dialects = Parser.getSupportedDialects(): string[];
+```typescript
+import { parse, PostgreSqlDialect } from 'sqlparser-rs';
+
+// String dialect names (recommended)
+parse('SELECT $1', 'postgresql');
+parse('SELECT `col` FROM t', 'mysql');
+
+// Or dialect instances
+parse('SELECT $1', new PostgreSqlDialect());
 ```
 
-#### Instance Methods (Builder Pattern)
+Supported dialect strings: `'generic'`, `'ansi'`, `'mysql'`, `'postgresql'`, `'sqlite'`, `'snowflake'`, `'redshift'`, `'mssql'`, `'clickhouse'`, `'bigquery'`, `'duckdb'`, `'databricks'`, `'hive'`, `'oracle'`
+
+### Parser Class
+
+For advanced use cases with options:
 
 ```typescript
 import { Parser, PostgreSqlDialect } from 'sqlparser-rs';
 
+// Static methods (same as top-level functions)
+Parser.parse('SELECT 1');
+Parser.parse('SELECT 1', 'postgresql');
+Parser.format('select 1');
+Parser.validate('SELECT 1');
+Parser.parseToJson('SELECT 1');      // Returns JSON string
+Parser.parseToString('SELECT 1');    // Returns formatted string
+Parser.getSupportedDialects();       // Returns dialect names
+
+// Builder pattern for custom options
 const parser = new Parser(new PostgreSqlDialect())
-  .withRecursionLimit(50)      // Set max recursion depth
-  .withOptions({               // Set parser options
-    trailingCommas: true
-  });
+  .withRecursionLimit(50)
+  .withOptions({ trailingCommas: true });
 
 const statements = parser.parse('SELECT * FROM users');
 ```
 
+### WASM Initialization
+
+The WASM module auto-initializes on import. For most use cases, no action is needed.
+
+If you need to ensure WASM is ready before calling sync APIs (e.g., in tests):
+
+```typescript
+import { ready, parse } from 'sqlparser-rs';
+
+// Wait for WASM to be ready
+await ready();
+
+// Now sync APIs are guaranteed to work
+const ast = parse('SELECT 1');
+```
+
 ### Dialects
 
-All dialects from the upstream Rust crate are supported:
+All dialects from the upstream Rust crate are supported. You can use string names directly with `parse()`, `format()`, and `validate()`:
 
 ```typescript
+// String names (recommended)
+parse('SELECT 1', 'postgresql');
+parse('SELECT 1', 'mysql');
+parse('SELECT 1', 'bigquery');
+
+// Or import dialect classes for type safety
 import {
   GenericDialect,      // Permissive, accepts most SQL syntax
   AnsiDialect,         // ANSI SQL standard
@@ -111,20 +150,21 @@ import {
   DuckDbDialect,       // DuckDB
   DatabricksDialect,   // Databricks
   HiveDialect,         // Apache Hive
+  OracleDialect,       // Oracle
 } from 'sqlparser-rs';
 
-// Create dialect from string
+// Create dialect from string programmatically
 import { dialectFromString } from 'sqlparser-rs';
 const dialect = dialectFromString('postgresql'); // Returns PostgreSqlDialect instance
 ```
 
 ### Error Handling
 
 ```typescript
-import { Parser, GenericDialect, ParserError } from 'sqlparser-rs';
+import { parse, ParserError } from 'sqlparser-rs';
 
 try {
-  Parser.parse('SELEC * FROM users', new GenericDialect());
+  parse('SELEC * FROM users');
 } catch (error) {
   if (error instanceof ParserError) {
     console.log('Parse error:', error.message);
@@ -140,9 +180,10 @@ try {
 Full TypeScript types are provided for the AST:
 
 ```typescript
-import type { Statement, Query, Expr, Ident, ObjectName } from 'sqlparser-rs';
+import { parse } from 'sqlparser-rs';
+import type { Statement, Query } from 'sqlparser-rs';
 
-const statements: Statement[] = Parser.parse('SELECT 1', new GenericDialect());
+const statements: Statement[] = parse('SELECT 1');
 
 // Statement is a discriminated union type
 for (const stmt of statements) {
@@ -191,7 +232,7 @@ npm test
 This package follows the upstream [sqlparser-rs](https://github.com/apache/datafusion-sqlparser-rs) version:
 
 - **Major.Minor** matches the upstream Rust crate version
-- **Patch** is for TypeScript binding fixes (e.g., `0.60.3` = upstream `0.60.0` + binding fix)
+- **Patch** is for TypeScript binding fixes (e.g., `0.60.3-rc2` = upstream `0.60.0` + binding fix)
 
 | This package | sqlparser-rs |
 |--------------|--------------|

ts/README.md

@@ -1,6 +1,6 @@
 {
   "name": "sqlparser-rs",
-  "version": "0.60.3",
+  "version": "0.60.3-rc2",
   "type": "module",
   "description": "A SQL parser for JavaScript and TypeScript, powered by datafusion-sqlparser-rs via WASM",
   "main": "dist/index.cjs",
@@ -44,7 +44,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/guan404ming/sqlparser-rs"
+    "url": "git+https://github.com/guan404ming/sqlparser-rs.git"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",

ts/package-lock.json

@@ -6,31 +6,21 @@
  *
  * @example
  * ```typescript
- * import { Parser, GenericDialect, PostgreSqlDialect } from 'sqlparser-rs';
+ * import { parse, format, validate } from 'sqlparser-rs';
  *
- * // Simple parsing
- * const statements = Parser.parse('SELECT * FROM users', new GenericDialect());
+ * // Simple parsing (uses generic dialect by default)
+ * const statements = parse('SELECT * FROM users');
  *
- * // With specific dialect
- * const pgStatements = Parser.parse(
- *   'SELECT * FROM users WHERE id = $1',
- *   new PostgreSqlDialect()
- * );
- *
- * // Builder pattern with options
- * const parser = new Parser(new PostgreSqlDialect())
- *   .withRecursionLimit(50)
- *   .withOptions({ trailingCommas: true });
- *
- * const ast = parser.parse('SELECT * FROM users');
+ * // With specific dialect (string name)
+ * const pgStatements = parse('SELECT * FROM users WHERE id = $1', 'postgresql');
  *
  * // Format SQL
- * const formatted = Parser.format('select * from users', new GenericDialect());
+ * const formatted = format('select * from users');
  * // Returns: "SELECT * FROM users"
  *
  * // Validate SQL
  * try {
- *   Parser.validate('SELECT * FRO users', new GenericDialect());
+ *   validate('SELECT * FRO users');
  * } catch (e) {
  *   console.log('Invalid SQL:', e.message);
  * }
@@ -39,9 +29,9 @@
  * @packageDocumentation
  */
 
-// Parser
-export { Parser, initWasm } from './parser.js';
-export type { ParserOptions } from './parser.js';
+// Parser (WASM auto-initializes on import, use ready() to await if needed)
+export { Parser, initWasm, ready, parse, validate, format } from './parser.js';
+export type { ParserOptions, DialectInput } from './parser.js';
 
 // Dialects
 export {