Simplify WASM API (#10)

* Simplify WASM init API to single init() function

Signed-off-by: Guan-Ming (Wesley) Chiu <105915352+guan404ming@users.noreply.github.com>

* Refactor WASM build process to consolidate targets

Signed-off-by: Guan-Ming (Wesley) Chiu <105915352+guan404ming@users.noreply.github.com>

---------

Signed-off-by: Guan-Ming (Wesley) Chiu <105915352+guan404ming@users.noreply.github.com>

Author: guan404ming

.github/workflows/ci.yml

@@ -40,13 +40,8 @@ jobs:
       - name: Install wasm-pack
         uses: jetli/wasm-pack-action@v0.4.0
 
-      - name: Build WASM (Node.js and Web)
-        run: |
-          wasm-pack build --target nodejs --out-dir ts/wasm
-          wasm-pack build --target web --out-dir ts/wasm-web
-          cp ts/wasm-web/sqlparser_rs_wasm.js ts/wasm/sqlparser_rs_wasm_web.js
-          cp ts/wasm-web/sqlparser_rs_wasm_bg.wasm ts/wasm/sqlparser_rs_wasm_web_bg.wasm
-          rm -rf ts/wasm-web
+      - name: Build WASM
+        run: wasm-pack build --target web --out-dir ts/wasm
 
       - name: Build TypeScript
         working-directory: ts

.gitignore

@@ -7,7 +7,6 @@ node_modules/
 # WASM build output
 /pkg
 /ts/wasm
-/ts/wasm-web
 
 # TypeScript build output
 /ts/dist

scripts/build.sh

@@ -6,35 +6,23 @@ echo "=========================================="
 echo "Building sqlparser-ts npm package"
 echo "=========================================="
 
-# Get the script directory
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
 
 echo ""
 echo "Project directory: $PROJECT_DIR"
 echo ""
 
-# Check for wasm-pack
 if ! command -v wasm-pack &> /dev/null; then
     echo "Error: wasm-pack is not installed."
     echo "Install it with: cargo install wasm-pack"
     echo "Or visit: https://rustwasm.github.io/wasm-pack/installer/"
     exit 1
 fi
 
-# Build WASM for Node.js
-echo "Step 1a: Building WASM module for Node.js..."
+echo "Step 1: Building WASM module..."
 cd "$PROJECT_DIR"
-wasm-pack build --target nodejs --out-dir ts/wasm
-
-# Build WASM for Web (browser)
-echo "Step 1b: Building WASM module for Web (browser)..."
-wasm-pack build --target web --out-dir ts/wasm-web
-
-# Copy web wasm files to wasm directory with _web suffix
-cp ts/wasm-web/sqlparser_rs_wasm.js ts/wasm/sqlparser_rs_wasm_web.js
-cp ts/wasm-web/sqlparser_rs_wasm_bg.wasm ts/wasm/sqlparser_rs_wasm_web_bg.wasm
-rm -rf ts/wasm-web
+wasm-pack build --target web --out-dir ts/wasm
 
 echo ""
 echo "Step 2: Installing npm dependencies..."
@@ -51,10 +39,10 @@ echo "Build complete!"
 echo "=========================================="
 echo ""
 echo "Output files:"
-echo "  - WASM: ts/wasm/"
-echo "  - ESM:  ts/dist/esm/"
-echo "  - CJS:  ts/dist/cts/"
-echo "  - Types: ts/dist/types/"
+echo "  - WASM:  ts/wasm/"
+echo "  - ESM:   ts/dist/index.mjs"
+echo "  - CJS:   ts/dist/index.cjs"
+echo "  - Types: ts/dist/index.d.{mts,cts}"
 echo ""
 echo "To run tests: cd ts && npm test"
 echo "To publish: cd ts && npm publish"

ts/README.md

@@ -25,7 +25,10 @@ npm install @guanmingchiu/sqlparser-ts
 ## Usage
 
 ```typescript
-import { parse, format, validate } from '@guanmingchiu/sqlparser-ts';
+import { init, parse, format, validate } from '@guanmingchiu/sqlparser-ts';
+
+// Initialize WASM module (must be called once before using any parser functions)
+await init();
 
 // Parse SQL into AST
 const ast = parse('SELECT * FROM users');
@@ -41,6 +44,19 @@ const sql = format('select   *   from   users');
 validate('SELECT * FROM users'); // ok
 ```
 
+### Vite Configuration
+
+WASM packages must be excluded from Vite's dev server [dependency pre-bundling](https://github.com/vitejs/vite/discussions/9256). This only affects the dev server. Production builds use Rollup instead of esbuild and handle WASM files correctly.
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['@guanmingchiu/sqlparser-ts'],
+  },
+});
+```
+
 ### Working with AST
 
 ```typescript

ts/package.json

@@ -20,8 +20,7 @@
   ],
   "scripts": {
     "build": "npm run build:wasm && npm run build:ts",
-    "build:wasm": "cd .. && wasm-pack build --target nodejs --out-dir ts/wasm && rm -f ts/wasm/.gitignore",
-    "build:wasm:web": "cd .. && wasm-pack build --target web --out-dir ts/wasm-web",
+    "build:wasm": "cd .. && wasm-pack build --target web --out-dir ts/wasm && rm -f ts/wasm/.gitignore",
     "build:ts": "tsdown",
     "test": "vitest run",
     "test:watch": "vitest",

ts/src/index.ts

@@ -4,7 +4,7 @@
  */
 
 // Parser
-export { Parser, initWasm, ready, parse, validate, format } from './parser.js';
+export { Parser, init, parse, validate, format } from './parser.js';
 export type { ParserOptions, DialectInput } from './parser.js';
 
 // Dialects

ts/src/parser.ts

@@ -4,7 +4,7 @@ import { ParserError } from './types/errors.js';
 import type { Statement } from './types/ast.js';
 import { getWasmModule } from './wasm.js';
 
-export { initWasm, ready } from './wasm.js';
+export { init } from './wasm.js';
 
 /** Dialect can be specified as a Dialect instance or a string name */
 export type DialectInput = Dialect | DialectName;

ts/src/wasm.ts

@@ -13,76 +13,51 @@ export interface WasmModule {
 
 let wasmModule: WasmModule | null = null;
 let initPromise: Promise<void> | null = null;
-let initStarted = false;
 
 const isBrowser = typeof window !== 'undefined' && typeof process === 'undefined';
 
-function startInit(): void {
-  if (initStarted) return;
-  initStarted = true;
-  initPromise = initWasm().catch(() => {
-    // Silently ignore init errors - they'll be thrown when APIs are used
-  });
-}
-
-// Start init on module load
-startInit();
-
 /** Get initialized WASM module or throw */
 export function getWasmModule(): WasmModule {
   if (wasmModule) {
     return wasmModule;
   }
   throw new WasmInitError(
-    'WASM module not yet initialized. Use the async import or wait for module to load: import("@guanmingchiu/sqlparser-ts").then(({ parse }) => parse(sql))'
+    'WASM module not yet initialized. Call `await init()` before using the parser.'
   );
 }
 
 /**
- * Wait for WASM module to be ready
- */
-export async function ready(): Promise<void> {
-  startInit();
-  await initPromise;
-}
-
-/**
- * Initialize the WASM module explicitly.
- * Usually not needed - the module auto-initializes on first use.
+ * Initialize the WASM module. Must be called before using any parser functions.
+ * Safe to call multiple times, subsequent calls are no-ops.
  */
-export async function initWasm(): Promise<void> {
+export async function init(): Promise<void> {
   if (wasmModule) {
     return;
   }
 
-  if (isBrowser) {
-    try {
-      const wasmJsUrl = new URL('../wasm/sqlparser_rs_wasm_web.js', import.meta.url);
-      const wasmBinaryUrl = new URL('../wasm/sqlparser_rs_wasm_web_bg.wasm', import.meta.url);
-
-      const wasm = await import(/* @vite-ignore */ wasmJsUrl.href);
-
-      if (typeof wasm.default === 'function') {
-        await wasm.default({ module_or_path: wasmBinaryUrl });
+  if (!initPromise) {
+    initPromise = (async () => {
+      try {
+        const wasm = await import(/* @vite-ignore */ '../wasm/sqlparser_rs_wasm.js');
+
+        if (isBrowser) {
+          const wasmUrl = new URL('../wasm/sqlparser_rs_wasm_bg.wasm', import.meta.url);
+          await wasm.default({ module_or_path: wasmUrl });
+        } else {
+          const { readFile } = await import(/* @vite-ignore */ 'node:fs/promises');
+          const wasmPath = new URL('../wasm/sqlparser_rs_wasm_bg.wasm', import.meta.url);
+          const bytes = await readFile(wasmPath);
+          await wasm.default({ module_or_path: bytes });
+        }
+
+        wasmModule = wasm as WasmModule;
+      } catch (error) {
+        throw new WasmInitError(
+          `Failed to load WASM module: ${error instanceof Error ? error.message : String(error)}`
+        );
       }
-
-      wasmModule = wasm as WasmModule;
-    } catch (error) {
-      throw new WasmInitError(
-        `Failed to load WASM module in browser: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-    return;
+    })();
   }
 
-  // Node.js
-  try {
-    const wasmUrl = new URL('../wasm/sqlparser_rs_wasm.js', import.meta.url);
-    const wasm = await import(/* @vite-ignore */ wasmUrl.href);
-    wasmModule = wasm as WasmModule;
-  } catch (error) {
-    throw new WasmInitError(
-      `Failed to load WASM module: ${error instanceof Error ? error.message : String(error)}`
-    );
-  }
+  await initPromise;
 }

ts/tests/builds.test.ts

@@ -60,22 +60,22 @@ describe('CJS build', () => {
   });
 
   test('parse works', async () => {
-    const { parse, ready } = require('../dist/index.cjs');
-    await ready();
+    const { parse, init } = require('../dist/index.cjs');
+    await init();
     const result = parse('SELECT 1');
     expect(Array.isArray(result)).toBe(true);
   });
 
   test('format works', async () => {
-    const { format, ready } = require('../dist/index.cjs');
-    await ready();
+    const { format, init } = require('../dist/index.cjs');
+    await init();
     const result = format('select 1');
     expect(result).toBe('SELECT 1');
   });
 
   test('dialect string works', async () => {
-    const { parse, ready } = require('../dist/index.cjs');
-    await ready();
+    const { parse, init } = require('../dist/index.cjs');
+    await init();
     const result = parse('SELECT $1', 'postgresql');
     expect(Array.isArray(result)).toBe(true);
   });

ts/tests/setup.ts

@@ -1,4 +1,4 @@
-import { initWasm } from '../src';
+import { init } from '../src';
 
 // Initialize WASM before running tests
-await initWasm();
+await init();