Update WASM connector. (#279)

* feat!: Make WASM constructor sync, add existing db/con options.
* test: Update dev tests to use updated wasm connector.
* docs: Update docs with updated wasm connector.

dev/index.html

@@ -45,9 +45,9 @@
     <span>
       Connector:
       <select id="connectors">
-        <option value="socket" selected>Socket</option>
+        <option value="wasm" selected>WASM</option>
+        <option value="socket">Socket</option>
         <option value="rest">REST</option>
-        <option value="wasm">WASM</option>
       </select>
     </span>
 
@@ -113,7 +113,7 @@
     const code = await specToModule(spec, { ...options, imports });
     const blob = new Blob([code], { type: 'text/javascript' });
     const url = URL.createObjectURL(blob);
-    return (await import(url /* @vite-ignore */)).default;
+    return (await import(/* @vite-ignore */ url)).default;
   }
 </script>
 </body>

dev/setup.js

@@ -16,7 +16,7 @@ export async function setDatabaseConnector(type, options) {
       connector = restConnector(options);
       break;
     case 'wasm':
-      connector = (wasm || (wasm = await wasmConnector(options)));
+      connector = wasm || (wasm = wasmConnector(options));
       break;
     default:
       throw new Error(`Unrecognized connector type: ${type}`);

docs/.vitepress/theme/Example.vue

@@ -7,18 +7,17 @@ let ready;
 
 function init() {
   if (!ready) {
-    ready = wasmConnector().then(wasm => {
-      coordinator().logger(null);
-      coordinator().databaseConnector(wasm);
-    });
+    coordinator().logger(null);
+    coordinator().databaseConnector(wasmConnector());
+    ready = true;
   }
   return ready;
 }
 
 export default {
   async mounted() {
     try {
-      await init();
+      init();
       const spec = yaml.parse(await fetch(withBase(this.spec)).then(r => r.text()));
       const view = await parseSpec(spec, { baseURL: location.origin + import.meta.env.BASE_URL });
       this.$refs.view.replaceChildren(view);

docs/api/core/connectors.md

@@ -28,8 +28,10 @@ Create a new HTTP rest connector to a DuckDB [data server](../duckdb/data-server
 `wasmConnector(options)`
 
 Create a new DuckDB-WASM connector with the given _options_.
-This method will instantiate a new DuckDB instance in-browser using Web Assembly.
+This method will instantiate a new DuckDB instance in-browser using Web Assembly. If no existing DuckDB-WASM instance provided as an option, a new instance is created lazily upon first access.
 
 The supported options are:
 
-- _log_: A Boolean flag (default `false`) that indicates if DuckDB-WASM logs should be written to the browser console.
+- _duckdb_: An existing DuckDB-WASM instance to query. If unspecified, a new instance is created.
+- _connection_: An existing connection to a DuckDB-WASM instance to use. If unspecified, a new connection is created.
+- _log_: A Boolean flag (default `false`) that indicates if DuckDB-WASM logs should be written to the browser console. This option is ignored when an existing _duckdb_ instance option is provided.

docs/get-started/index.md

@@ -15,8 +15,7 @@ import * as vg from "@uwdata/vgplot";
 
 // configure the coordinator to use DuckDB-WASM
 // creates a new database instance running in-browser
-const wasm = await vg.wasmConnector();
-vg.coordinator().databaseConnector(wasm);
+vg.coordinator().databaseConnector(vg.wasmConnector());
 
 // load data into the database
 // executes a query generated by the loadCSV helper
@@ -48,8 +47,8 @@ For local installation you should have `npm` and `node` version 18 or higher.
 
 ### Run Examples
 
-After installation, you can run examples locally from a DuckDB server.
+After installation, you can run examples locally, using either DuckDB-WASM or a DuckDB server.
 
-- Run `npm run server` to launch a local DuckDB server.
 - Run `npm run dev` to start a dev web server with examples.
   The `socket` and `rest` connectors will only work if a local DuckDB server is running.
+- Run `npm run server` to launch a local DuckDB server.

packages/core/src/connectors/wasm.js

@@ -1,14 +1,28 @@
 import * as duckdb from '@duckdb/duckdb-wasm';
 
-export async function wasmConnector(options) {
-  const db = await initDatabase(options);
-  const con = await db.connect();
+export function wasmConnector(options = {}) {
+  const { duckdb, connection, ...opts } = options;
+  let db = duckdb;
+  let con = connection;
+
+  async function getDuckDB() {
+    if (!db) db = await initDatabase(opts);
+    return db;
+  }
+
+  async function getConnection() {
+    if (!con) {
+      con = await (await getDuckDB()).connect();
+    }
+    return con;
+  }
 
   return {
-    db,
-    con,
+    getDuckDB,
+    getConnection,
     query: async query => {
       const { type, sql } = query;
+      const con = await getConnection();
       const result = await con.query(sql);
       return type === 'exec' ? undefined
         : type === 'arrow' ? result