sqlparser-rs 0.60.2 → 0.60.3-rc2

package/README.md

@@ -26,25 +26,22 @@ 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);
 }
@@ -52,46 +49,82 @@ try {
 
 ## 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:
@@ -191,7 +224,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.2` = 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 |
 |--------------|--------------|

package/dist/index.cjs

@@ -0,0 +1,526 @@
+
+//#region src/dialects.ts
+/**
+* Generic SQL dialect - accepts most SQL syntax
+*/
+var GenericDialect = class {
+	constructor() {
+		this.name = "generic";
+	}
+};
+/**
+* ANSI SQL standard dialect
+*/
+var AnsiDialect = class {
+	constructor() {
+		this.name = "ansi";
+	}
+};
+/**
+* MySQL dialect
+*/
+var MySqlDialect = class {
+	constructor() {
+		this.name = "mysql";
+	}
+};
+/**
+* PostgreSQL dialect
+*/
+var PostgreSqlDialect = class {
+	constructor() {
+		this.name = "postgresql";
+	}
+};
+/**
+* SQLite dialect
+*/
+var SQLiteDialect = class {
+	constructor() {
+		this.name = "sqlite";
+	}
+};
+/**
+* Snowflake dialect
+*/
+var SnowflakeDialect = class {
+	constructor() {
+		this.name = "snowflake";
+	}
+};
+/**
+* Amazon Redshift dialect
+*/
+var RedshiftDialect = class {
+	constructor() {
+		this.name = "redshift";
+	}
+};
+/**
+* Microsoft SQL Server dialect
+*/
+var MsSqlDialect = class {
+	constructor() {
+		this.name = "mssql";
+	}
+};
+/**
+* ClickHouse dialect
+*/
+var ClickHouseDialect = class {
+	constructor() {
+		this.name = "clickhouse";
+	}
+};
+/**
+* Google BigQuery dialect
+*/
+var BigQueryDialect = class {
+	constructor() {
+		this.name = "bigquery";
+	}
+};
+/**
+* DuckDB dialect
+*/
+var DuckDbDialect = class {
+	constructor() {
+		this.name = "duckdb";
+	}
+};
+/**
+* Databricks dialect
+*/
+var DatabricksDialect = class {
+	constructor() {
+		this.name = "databricks";
+	}
+};
+/**
+* Apache Hive dialect
+*/
+var HiveDialect = class {
+	constructor() {
+		this.name = "hive";
+	}
+};
+/**
+* Oracle dialect
+*/
+var OracleDialect = class {
+	constructor() {
+		this.name = "oracle";
+	}
+};
+/**
+* All supported dialect names
+*/
+const SUPPORTED_DIALECTS = [
+	"generic",
+	"ansi",
+	"mysql",
+	"postgresql",
+	"sqlite",
+	"snowflake",
+	"redshift",
+	"mssql",
+	"clickhouse",
+	"bigquery",
+	"duckdb",
+	"databricks",
+	"hive",
+	"oracle"
+];
+/**
+* Map of dialect names to dialect classes
+*/
+const DIALECT_MAP = {
+	generic: GenericDialect,
+	ansi: AnsiDialect,
+	mysql: MySqlDialect,
+	postgresql: PostgreSqlDialect,
+	sqlite: SQLiteDialect,
+	snowflake: SnowflakeDialect,
+	redshift: RedshiftDialect,
+	mssql: MsSqlDialect,
+	clickhouse: ClickHouseDialect,
+	bigquery: BigQueryDialect,
+	duckdb: DuckDbDialect,
+	databricks: DatabricksDialect,
+	hive: HiveDialect,
+	oracle: OracleDialect
+};
+/**
+* Create a dialect instance from a string name
+*
+* @param name - The name of the dialect (case-insensitive)
+* @returns A dialect instance, or undefined if the dialect is not recognized
+*
+* @example
+* ```typescript
+* const dialect = dialectFromString('postgresql');
+* if (dialect) {
+*   const ast = Parser.parse('SELECT 1', dialect);
+* }
+* ```
+*/
+function dialectFromString(name) {
+	const normalized = name.toLowerCase();
+	const DialectClass = DIALECT_MAP[{
+		postgres: "postgresql",
+		pg: "postgresql",
+		sqlserver: "mssql",
+		duck: "duckdb"
+	}[normalized] ?? normalized];
+	return DialectClass ? new DialectClass() : void 0;
+}
+
+//#endregion
+//#region src/types/errors.ts
+/**
+* Error thrown when SQL parsing fails
+*/
+var ParserError = class ParserError extends Error {
+	constructor(message, location) {
+		super(message);
+		this.name = "ParserError";
+		this.location = location;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, ParserError);
+	}
+	/**
+	* Create a ParserError from a WASM error object
+	*/
+	static fromWasmError(error) {
+		if (typeof error === "string") return new ParserError(error);
+		if (error && typeof error === "object") {
+			const err = error;
+			return new ParserError(typeof err.message === "string" ? err.message : String(error), typeof err.line === "number" && typeof err.column === "number" ? {
+				line: err.line,
+				column: err.column
+			} : void 0);
+		}
+		return new ParserError(String(error));
+	}
+};
+/**
+* Error thrown when WASM module fails to initialize
+*/
+var WasmInitError = class WasmInitError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "WasmInitError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, WasmInitError);
+	}
+};
+
+//#endregion
+//#region src/parser.ts
+function resolveDialect(dialect = "generic") {
+	if (typeof dialect === "string") {
+		const resolved = dialectFromString(dialect);
+		if (!resolved) throw new Error(`Unknown dialect: ${dialect}`);
+		return resolved;
+	}
+	return dialect;
+}
+let wasmModule = null;
+let initPromise = null;
+let initStarted = false;
+const isBrowser = typeof window !== "undefined" && typeof process === "undefined";
+function startInit() {
+	if (initStarted) return;
+	initStarted = true;
+	initPromise = initWasm().catch(() => {});
+}
+startInit();
+function getWasmModule() {
+	if (wasmModule) return wasmModule;
+	throw new WasmInitError("WASM module not yet initialized. Use the async import or wait for module to load: import(\"sqlparser-rs\").then(({ parse }) => parse(sql))");
+}
+/**
+* Wait for WASM to be ready (useful for ensuring sync APIs work)
+*/
+async function ready() {
+	startInit();
+	await initPromise;
+}
+/**
+* Initialize the WASM module.
+* This must be called before using the Parser in browsers and Node.js ESM.
+* In Node.js CommonJS, the module is loaded automatically.
+*
+* @example
+* ```typescript
+* import { initWasm, Parser, GenericDialect } from 'sqlparser-rs';
+*
+* // Initialize first
+* await initWasm();
+*
+* // Then use the parser
+* const ast = Parser.parse('SELECT 1', new GenericDialect());
+* ```
+*/
+async function initWasm() {
+	if (wasmModule) return;
+	if (isBrowser) {
+		try {
+			const wasmJsUrl = new URL("../wasm/sqlparser_rs_wasm_web.js", require("url").pathToFileURL(__filename).href);
+			const wasmBinaryUrl = new URL("../wasm/sqlparser_rs_wasm_web_bg.wasm", require("url").pathToFileURL(__filename).href);
+			const wasm = await import(
+				/* @vite-ignore */
+				wasmJsUrl.href
+);
+			if (typeof wasm.default === "function") await wasm.default(wasmBinaryUrl);
+			wasmModule = wasm;
+		} catch (error) {
+			throw new WasmInitError(`Failed to load WASM module in browser: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		return;
+	}
+	try {
+		wasmModule = await import(
+			/* @vite-ignore */
+			new URL("../wasm/sqlparser_rs_wasm.js", require("url").pathToFileURL(__filename).href).href
+);
+	} catch (error) {
+		throw new WasmInitError(`Failed to load WASM module: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* SQL Parser
+*
+* Parses SQL statements into an Abstract Syntax Tree (AST).
+*
+* @example
+* ```typescript
+* import { Parser, PostgreSqlDialect } from 'sqlparser-rs';
+*
+* // Simple parsing
+* const statements = Parser.parse('SELECT * FROM users', new PostgreSqlDialect());
+*
+* // With builder pattern
+* const parser = new Parser(new PostgreSqlDialect())
+*   .withRecursionLimit(50)
+*   .withOptions({ trailingCommas: true });
+*
+* const ast = parser.parse('SELECT * FROM users');
+* ```
+*/
+var Parser = class Parser {
+	/**
+	* Create a new parser instance
+	*
+	* @param dialect - The SQL dialect to use (defaults to GenericDialect)
+	*/
+	constructor(dialect = new GenericDialect()) {
+		this.dialect = dialect;
+		this.options = {};
+	}
+	/**
+	* Set the recursion limit for parsing nested expressions
+	*
+	* @param limit - Maximum recursion depth
+	* @returns This parser instance for chaining
+	*/
+	withRecursionLimit(limit) {
+		this.options.recursionLimit = limit;
+		return this;
+	}
+	/**
+	* Set parser options
+	*
+	* @param options - Parser options
+	* @returns This parser instance for chaining
+	*/
+	withOptions(options) {
+		this.options = {
+			...this.options,
+			...options
+		};
+		return this;
+	}
+	/**
+	* Parse SQL statements
+	*
+	* @param sql - SQL string to parse
+	* @returns Array of parsed statements
+	*/
+	parse(sql) {
+		const wasm = getWasmModule();
+		try {
+			if (Object.keys(this.options).length > 0) return wasm.parse_sql_with_options(this.dialect.name, sql, this.options);
+			else return wasm.parse_sql(this.dialect.name, sql);
+		} catch (error) {
+			throw ParserError.fromWasmError(error);
+		}
+	}
+	/**
+	* Parse SQL statements
+	*
+	* @param sql - SQL string to parse
+	* @param dialect - SQL dialect to use (string name or Dialect instance, defaults to 'generic')
+	* @returns Array of parsed statements
+	*
+	* @example
+	* ```typescript
+	* // Using default dialect
+	* const statements = Parser.parse('SELECT 1');
+	*
+	* // Using string dialect name
+	* const pgStatements = Parser.parse('SELECT $1', 'postgresql');
+	*
+	* // Using dialect instance
+	* const mysqlStatements = Parser.parse('SELECT 1', new MySqlDialect());
+	* ```
+	*/
+	static parse(sql, dialect = "generic") {
+		return new Parser(resolveDialect(dialect)).parse(sql);
+	}
+	/**
+	* Parse SQL and return the AST as a JSON string
+	*
+	* @param sql - SQL string to parse
+	* @param dialect - SQL dialect to use (string name or Dialect instance, defaults to 'generic')
+	* @returns JSON string representation of the AST
+	*/
+	static parseToJson(sql, dialect = "generic") {
+		const wasm = getWasmModule();
+		try {
+			return wasm.parse_sql_to_json_string(resolveDialect(dialect).name, sql);
+		} catch (error) {
+			throw ParserError.fromWasmError(error);
+		}
+	}
+	/**
+	* Parse SQL and return a formatted string representation
+	*
+	* @param sql - SQL string to parse
+	* @param dialect - SQL dialect to use (string name or Dialect instance, defaults to 'generic')
+	* @returns String representation of the parsed SQL
+	*/
+	static parseToString(sql, dialect = "generic") {
+		const wasm = getWasmModule();
+		try {
+			return wasm.parse_sql_to_string(resolveDialect(dialect).name, sql);
+		} catch (error) {
+			throw ParserError.fromWasmError(error);
+		}
+	}
+	/**
+	* Format SQL by parsing and regenerating it (round-trip)
+	*
+	* @param sql - SQL string to format
+	* @param dialect - SQL dialect to use (string name or Dialect instance, defaults to 'generic')
+	* @returns Formatted SQL string
+	*/
+	static format(sql, dialect = "generic") {
+		const wasm = getWasmModule();
+		try {
+			return wasm.format_sql(resolveDialect(dialect).name, sql);
+		} catch (error) {
+			throw ParserError.fromWasmError(error);
+		}
+	}
+	/**
+	* Validate SQL syntax without returning the full AST
+	*
+	* @param sql - SQL string to validate
+	* @param dialect - SQL dialect to use (string name or Dialect instance, defaults to 'generic')
+	* @returns true if valid, throws ParserError if invalid
+	*/
+	static validate(sql, dialect = "generic") {
+		const wasm = getWasmModule();
+		try {
+			return wasm.validate_sql(resolveDialect(dialect).name, sql);
+		} catch (error) {
+			throw ParserError.fromWasmError(error);
+		}
+	}
+	/**
+	* Get the list of supported dialect names
+	*/
+	static getSupportedDialects() {
+		return getWasmModule().get_supported_dialects();
+	}
+};
+/**
+* Parse SQL statements (convenience function)
+*
+* @param sql - SQL string to parse
+* @param dialect - SQL dialect to use (string name or Dialect instance, defaults to 'generic')
+* @returns Array of parsed statements
+*
+* @example
+* ```typescript
+* import { parse } from 'sqlparser-rs';
+*
+* const statements = parse('SELECT * FROM users');
+* const pgStatements = parse('SELECT $1', 'postgresql');
+* ```
+*/
+function parse(sql, dialect = "generic") {
+	return Parser.parse(sql, dialect);
+}
+/**
+* Validate SQL syntax (convenience function)
+*
+* @param sql - SQL string to validate
+* @param dialect - SQL dialect to use (string name or Dialect instance, defaults to 'generic')
+* @returns true if valid, throws ParserError if invalid
+*
+* @example
+* ```typescript
+* import { validate } from 'sqlparser-rs';
+*
+* if (validate('SELECT * FROM users')) {
+*   console.log('Valid SQL!');
+* }
+* ```
+*/
+function validate(sql, dialect = "generic") {
+	return Parser.validate(sql, dialect);
+}
+/**
+* Format SQL by parsing and regenerating it (convenience function)
+*
+* @param sql - SQL string to format
+* @param dialect - SQL dialect to use (string name or Dialect instance, defaults to 'generic')
+* @returns Formatted SQL string
+*
+* @example
+* ```typescript
+* import { format } from 'sqlparser-rs';
+*
+* const formatted = format('select * from users');
+* // Returns: "SELECT * FROM users"
+* ```
+*/
+function format(sql, dialect = "generic") {
+	return Parser.format(sql, dialect);
+}
+
+//#endregion
+exports.AnsiDialect = AnsiDialect;
+exports.BigQueryDialect = BigQueryDialect;
+exports.ClickHouseDialect = ClickHouseDialect;
+exports.DatabricksDialect = DatabricksDialect;
+exports.DuckDbDialect = DuckDbDialect;
+exports.GenericDialect = GenericDialect;
+exports.HiveDialect = HiveDialect;
+exports.MsSqlDialect = MsSqlDialect;
+exports.MySqlDialect = MySqlDialect;
+exports.OracleDialect = OracleDialect;
+exports.Parser = Parser;
+exports.ParserError = ParserError;
+exports.PostgreSqlDialect = PostgreSqlDialect;
+exports.RedshiftDialect = RedshiftDialect;
+exports.SQLiteDialect = SQLiteDialect;
+exports.SUPPORTED_DIALECTS = SUPPORTED_DIALECTS;
+exports.SnowflakeDialect = SnowflakeDialect;
+exports.WasmInitError = WasmInitError;
+exports.dialectFromString = dialectFromString;
+exports.format = format;
+exports.initWasm = initWasm;
+exports.parse = parse;
+exports.ready = ready;
+exports.validate = validate;