Add ggsql WebAssembly library (#126)

* Build ggsql/polars-sql for wasm32-unknown-unknown

* Add GitHub CI to build wasm package

* cargo fmt

* Make register a strictly required method

* cargo fmt

* Use GGSQL_PREFIX

* Add additional register argument where required

* Use existing infrastructure to manipulate CTEs

* Keep clippy, the formatter, and pytest happy

Author: georgestagg

.cargo/config.toml

@@ -0,0 +1,4 @@
+[target.wasm32-unknown-unknown]
+rustflags = [
+  "-C", "link-args=-z stack-size=16777216",
+]

.github/workflows/wasm.yaml

@@ -0,0 +1,56 @@
+name: wasm.yaml
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Increase disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
+          sudo docker image prune --all --force
+          sudo docker builder prune -a
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install tree-sitter-cli
+        run: npm install -g tree-sitter-cli
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install LLVM
+        run: sudo apt-get install -y llvm
+
+      - name: Caching
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: ${{ runner.os }}-build
+          cache-on-failure: true
+
+      - name: Install wasm-opt
+        run: cargo install wasm-opt
+
+      - name: Install wasm-pack
+        run: cargo install wasm-pack
+
+      - name: Build WASM package
+        working-directory: ggsql-wasm
+        run: wasm-pack build --target web --profile wasm --no-opt
+
+      - name: Optimise WASM binary
+        working-directory: ggsql-wasm
+        run: wasm-opt pkg/ggsql_wasm_bg.wasm -o pkg/ggsql_wasm_bg.wasm -Oz --all-features

.gitignore

@@ -104,6 +104,7 @@ docs/_build/
 .env.local
 .env.production
 config.toml
+!.cargo/config.toml
 secrets.toml
 
 # Generated documentation

CLAUDE.md

@@ -994,10 +994,12 @@ spec = ggsql.execute(
 )
 ```
 
+Required methods for custom readers (in addition to `execute_sql`):
+
+- `register(name: str, df: polars.DataFrame, replace: bool = False) -> None` - Register a DataFrame as a table
+
 Optional methods for custom readers:
 
-- `supports_register() -> bool` - Return `True` if registration is supported
-- `register(name: str, df: polars.DataFrame) -> None` - Register a DataFrame as a table
 - `unregister(name: str) -> None` - Unregister a previously registered table
 
 Native readers (e.g., `DuckDBReader`) use an optimized fast path, while custom Python readers are automatically bridged via IPC serialization.
@@ -1091,15 +1093,15 @@ Where `<global_mapping>` can be:
 
 ### Clause Types
 
-| Clause         | Repeatable | Purpose            | Example                              |
-| -------------- | ---------- | ------------------ | ------------------------------------ |
-| `VISUALISE`    | ✅ Yes     | Entry point        | `VISUALISE date AS x, revenue AS y`  |
-| `DRAW`         | ✅ Yes     | Define layers      | `DRAW line MAPPING date AS x, value AS y` |
-| `SCALE`        | ✅ Yes     | Configure scales   | `SCALE x VIA date`                            |
-| `FACET`        | ❌ No      | Small multiples    | `FACET WRAP region`                  |
-| `COORD`        | ❌ No      | Coordinate system  | `COORD cartesian SETTING xlim => [0,100]` |
-| `LABEL`        | ❌ No      | Text labels        | `LABEL title => 'My Chart', x => 'Date'`   |
-| `THEME`        | ❌ No      | Visual styling     | `THEME minimal`                      |
+| Clause      | Repeatable | Purpose           | Example                                   |
+| ----------- | ---------- | ----------------- | ----------------------------------------- |
+| `VISUALISE` | ✅ Yes     | Entry point       | `VISUALISE date AS x, revenue AS y`       |
+| `DRAW`      | ✅ Yes     | Define layers     | `DRAW line MAPPING date AS x, value AS y` |
+| `SCALE`     | ✅ Yes     | Configure scales  | `SCALE x VIA date`                        |
+| `FACET`     | ❌ No      | Small multiples   | `FACET WRAP region`                       |
+| `COORD`     | ❌ No      | Coordinate system | `COORD cartesian SETTING xlim => [0,100]` |
+| `LABEL`     | ❌ No      | Text labels       | `LABEL title => 'My Chart', x => 'Date'`  |
+| `THEME`     | ❌ No      | Visual styling    | `THEME minimal`                           |
 
 ### DRAW Clause (Layers)
 

Cargo.toml

@@ -3,7 +3,8 @@ members = [
     "tree-sitter-ggsql",
     "src",
     "ggsql-jupyter",
-    "ggsql-python"
+    "ggsql-python",
+    "ggsql-wasm"
 ]
 # ggsql-python is excluded from default builds because it's a PyO3 extension
 # that requires Python dev headers. Build it separately with maturin.
@@ -25,18 +26,18 @@ description = "SQL extension for declarative data visualization"
 
 [workspace.dependencies]
 # Parsing
-tree-sitter = "0.25"
+tree-sitter = "0.26"
 csscolorparser = "0.8.1"
 
 # Data processing
-polars = { version = "0.52", features = ["lazy", "sql", "ipc"] }
+polars = { version = "0.52", default-features = false }
 polars-ops = { version = "0.52", features = ["pivot"] }
 
 # Readers
 duckdb = { version = "1.4", features = ["bundled", "vtab-arrow"] }
 arrow = { version = "56", default-features = false, features = ["ipc"] }
 postgres = "0.19"
-sqlx = { version = "0.8", features = ["postgres", "runtime-tokio-rustls"] }
+sqlx = { version = "0.8", features = ["postgres"] }
 rusqlite = "0.32"
 
 # Writers
@@ -68,7 +69,15 @@ uuid = { version = "1.0", features = ["v4"] }
 
 # Web server
 axum = "0.7"
-tokio = { version = "1.35", features = ["full"] }
+tokio = { version = "1.35", default-features = false }
 tower-http = { version = "0.5", features = ["cors", "trace"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+
+[profile.wasm]
+inherits = "release"
+opt-level = "z"
+lto = true
+codegen-units = 1
+strip = true
+panic = "abort"

ggsql-python/README.md

@@ -125,10 +125,9 @@ reader = ggsql.DuckDBReader("duckdb:///path/to/file.db")  # File database
 
 **Methods:**
 
-- `register(name: str, df: polars.DataFrame)` - Register a DataFrame as a queryable table
+- `register(name: str, df: polars.DataFrame, replace: bool = False)` - Register a DataFrame as a queryable table
 - `unregister(name: str)` - Unregister a previously registered table
 - `execute_sql(sql: str) -> polars.DataFrame` - Execute SQL and return results
-- `supports_register() -> bool` - Check if registration is supported
 
 #### `VegaLiteWriter()`
 
@@ -262,11 +261,10 @@ writer = ggsql.VegaLiteWriter()
 json_output = writer.render(spec)
 ```
 
-**Optional methods** for custom readers:
+**Additional methods** for custom readers:
 
-- `supports_register() -> bool` - Return `True` if your reader supports DataFrame registration
-- `register(name: str, df: polars.DataFrame) -> None` - Register a DataFrame as a queryable table
-- `unregister(name: str) -> None` - Unregister a previously registered table
+- `register(name: str, df: polars.DataFrame, replace: bool = False) -> None` - Register a DataFrame as a queryable table (required)
+- `unregister(name: str) -> None` - Unregister a previously registered table (optional)
 
 ```python
 class AdvancedReader:
@@ -279,10 +277,7 @@ class AdvancedReader:
         # Your SQL execution logic here
         ...
 
-    def supports_register(self) -> bool:
-        return True
-
-    def register(self, name: str, df: pl.DataFrame) -> None:
+    def register(self, name: str, df: pl.DataFrame, replace: bool = False) -> None:
         self.tables[name] = df
 
     def unregister(self, name: str) -> None:
@@ -313,11 +308,8 @@ class IbisReader:
     def execute_sql(self, sql: str) -> pl.DataFrame:
         return self.con.con.execute(sql).pl()
 
-    def supports_register(self) -> bool:
-        return True
-
-    def register(self, name: str, df: pl.DataFrame) -> None:
-        self.con.create_table(name, df.to_arrow(), overwrite=True)
+    def register(self, name: str, df: pl.DataFrame, replace: bool = False) -> None:
+        self.con.create_table(name, df.to_arrow(), overwrite=replace)
 
     def unregister(self, name: str) -> None:
         self.con.drop_table(name)

ggsql-python/src/lib.rs

@@ -138,29 +138,19 @@ impl Reader for PyReaderBridge {
         })
     }
 
-    fn supports_register(&self) -> bool {
-        Python::attach(|py| {
-            self.obj
-                .bind(py)
-                .call_method0("supports_register")
-                .and_then(|r| r.extract::<bool>())
-                .unwrap_or(false)
-        })
-    }
-
-    fn register(&mut self, name: &str, df: DataFrame) -> ggsql::Result<()> {
+    fn register(&self, name: &str, df: DataFrame, replace: bool) -> ggsql::Result<()> {
         Python::attach(|py| {
             let py_df =
                 polars_to_py(py, &df).map_err(|e| GgsqlError::ReaderError(e.to_string()))?;
             self.obj
                 .bind(py)
-                .call_method1("register", (name, py_df))
+                .call_method1("register", (name, py_df, replace))
                 .map_err(|e| GgsqlError::ReaderError(format!("Reader.register() failed: {}", e)))?;
             Ok(())
         })
     }
 
-    fn unregister(&mut self, name: &str) -> ggsql::Result<()> {
+    fn unregister(&self, name: &str) -> ggsql::Result<()> {
         Python::attach(|py| {
             self.obj
                 .bind(py)
@@ -254,10 +244,17 @@ impl PyDuckDBReader {
     /// ------
     /// ValueError
     ///     If registration fails or the table name is invalid.
-    fn register(&mut self, py: Python<'_>, name: &str, df: &Bound<'_, PyAny>) -> PyResult<()> {
+    #[pyo3(signature = (name, df, replace=false))]
+    fn register(
+        &self,
+        py: Python<'_>,
+        name: &str,
+        df: &Bound<'_, PyAny>,
+        replace: bool,
+    ) -> PyResult<()> {
         let rust_df = py_to_polars(py, df)?;
         self.inner
-            .register(name, rust_df)
+            .register(name, rust_df, replace)
             .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
     }
 
@@ -272,7 +269,7 @@ impl PyDuckDBReader {
     /// ------
     /// ValueError
     ///     If the table wasn't registered via this reader or unregistration fails.
-    fn unregister(&mut self, name: &str) -> PyResult<()> {
+    fn unregister(&self, name: &str) -> PyResult<()> {
         self.inner
             .unregister(name)
             .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
@@ -302,16 +299,6 @@ impl PyDuckDBReader {
         polars_to_py(py, &df)
     }
 
-    /// Check if this reader supports DataFrame registration.
-    ///
-    /// Returns
-    /// -------
-    /// bool
-    ///     True if register() is supported, False otherwise.
-    fn supports_register(&self) -> bool {
-        self.inner.supports_register()
-    }
-
     /// Execute a ggsql query and return the visualization specification.
     ///
     /// This is the main entry point for creating visualizations. It parses

ggsql-python/tests/test_ggsql.py

@@ -85,10 +85,6 @@ def test_register_and_query(self):
         assert isinstance(result, pl.DataFrame)
         assert result.shape == (2, 2)
 
-    def test_supports_register(self):
-        reader = ggsql.DuckDBReader("duckdb://memory")
-        assert reader.supports_register() is True
-
     def test_invalid_connection_string(self):
         with pytest.raises(ValueError):
             ggsql.DuckDBReader("invalid://connection")
@@ -396,25 +392,6 @@ def test_can_introspect_spec(self):
 class TestCustomReader:
     """Tests for custom Python reader support."""
 
-    def test_simple_custom_reader(self):
-        """Custom reader with execute_sql() method works."""
-
-        class SimpleReader:
-            def __init__(self):
-                self.conn = duckdb.connect()
-                self.conn.execute(
-                    "CREATE TABLE data AS SELECT * FROM ("
-                    "VALUES (1, 10), (2, 20), (3, 30)"
-                    ") AS t(x, y)"
-                )
-
-            def execute_sql(self, sql: str) -> pl.DataFrame:
-                return self.conn.execute(sql).pl()
-
-        reader = SimpleReader()
-        spec = ggsql.execute("SELECT * FROM data VISUALISE x, y DRAW point", reader)
-        assert spec.metadata()["rows"] == 3
-
     def test_custom_reader_with_register(self):
         """Custom reader with register() support."""
 
@@ -425,10 +402,7 @@ def __init__(self):
             def execute_sql(self, sql: str) -> pl.DataFrame:
                 return self.conn.execute(sql).pl()
 
-            def supports_register(self) -> bool:
-                return True
-
-            def register(self, name: str, df: pl.DataFrame) -> None:
+            def register(self, name: str, df: pl.DataFrame, _replace: bool) -> None:
                 self.conn.register(name, df)
 
         reader = RegisterReader()
@@ -479,6 +453,9 @@ def __init__(self):
             def execute_sql(self, sql: str) -> pl.DataFrame:
                 return self.conn.execute(sql).pl()
 
+            def register(self, name: str, df: pl.DataFrame, _replace: bool) -> None:
+                self.conn.register(name, df)
+
         reader = DuckDBBackedReader()
         spec = ggsql.execute(
             "SELECT * FROM data VISUALISE x, y, category AS color DRAW point",
@@ -499,15 +476,17 @@ class RecordingReader:
             def __init__(self):
                 self.conn = duckdb.connect()
                 self.conn.execute(
-                    "CREATE TABLE data AS SELECT * FROM ("
-                    "VALUES (1, 2)) AS t(x, y)"
+                    "CREATE TABLE data AS SELECT * FROM (VALUES (1, 2)) AS t(x, y)"
                 )
                 self.execute_calls = []
 
             def execute_sql(self, sql: str) -> pl.DataFrame:
                 self.execute_calls.append(sql)
                 return self.conn.execute(sql).pl()
 
+            def register(self, name: str, df: pl.DataFrame, _replace: bool) -> None:
+                self.conn.register(name, df)
+
         reader = RecordingReader()
         ggsql.execute(
             "SELECT * FROM data VISUALISE x, y DRAW point",
@@ -530,11 +509,10 @@ def __init__(self):
             def execute_sql(self, sql: str) -> pl.DataFrame:
                 return self.con.con.execute(sql).pl()
 
-            def supports_register(self) -> bool:
-                return True
-
-            def register(self, name: str, df: pl.DataFrame) -> None:
-                self.con.create_table(name, df.to_arrow(), overwrite=True)
+            def register(
+                self, name: str, df: pl.DataFrame, replace: bool = True
+            ) -> None:
+                self.con.create_table(name, df.to_arrow(), overwrite=replace)
 
             def unregister(self, name: str) -> None:
                 self.con.drop_table(name)