@sqlrooms/motherduck 0.27.0 → 0.28.0

package/README.md

@@ -1,8 +1,55 @@
-[MotherDuck](https://motherduck.com/) is a managed DuckDB-in-the-cloud service that enables you to run DuckDB queries both in your browser and in the cloud.
+MotherDuck connector for SQLRooms.
 
-This package exposes a `createWasmMotherDuckDbConnector` function, which allows SQLRooms to connect to MotherDuck.
-The connector is implemented using the [`@motherduck/wasm-client`](https://motherduck.com/docs/sql-reference/wasm-client/) library which is a customized version of [`@duckdb/duckdb-wasm`](https://github.com/duckdb/duckdb-wasm/tree/main/packages/duckdb-wasm) capable of querying MotherDuck datasets in the cloud from the browser.
+`@sqlrooms/motherduck` exposes a DuckDB connector implementation backed by [`@motherduck/wasm-client`](https://motherduck.com/docs/sql-reference/wasm-client/), so SQLRooms apps can query MotherDuck from the browser.
+
+## Installation
+
+```bash
+npm install @sqlrooms/motherduck @sqlrooms/room-shell
+```
+
+## Quick start
+
+```tsx
+import {createWasmMotherDuckDbConnector} from '@sqlrooms/motherduck';
+import {
+  createRoomShellSlice,
+  createRoomStore,
+  RoomShellSliceState,
+} from '@sqlrooms/room-shell';
+
+type RoomState = RoomShellSliceState;
+
+export function createStore(mdToken: string) {
+  return createRoomStore<RoomState>((set, get, store) => ({
+    ...createRoomShellSlice({
+      connector: createWasmMotherDuckDbConnector({
+        mdToken,
+      }),
+    })(set, get, store),
+  }));
+}
+```
+
+## Connector options
+
+`createWasmMotherDuckDbConnector(options)` accepts:
+
+- MotherDuck WASM client connection params (for example `mdToken`)
+- optional `initializationQuery` string to run at connector init
+
+## Type guard and advanced access
+
+```ts
+import {isWasmMotherDuckDbConnector} from '@sqlrooms/motherduck';
+
+const connector = await roomStore.getState().db.getConnector();
+if (isWasmMotherDuckDbConnector(connector)) {
+  const connection = connector.getConnection();
+  // access low-level MotherDuck WASM connection APIs
+}
+```
 
 ## Example
 
-See [`MotherDuck Cloud Query Editor`](/examples#motherduck-cloud-query-editor) for a usage example.
+- MotherDuck cloud query example: https://github.com/sqlrooms/examples/tree/main/query-motherduck

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqlrooms/motherduck",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@motherduck/wasm-client": "^0.8.0",
-    "@sqlrooms/duckdb": "0.27.0",
+    "@sqlrooms/duckdb": "0.28.0",
     "apache-arrow": "^17.0.0"
   },
   "scripts": {
@@ -30,5 +30,5 @@
     "typecheck": "tsc --noEmit",
     "typedoc": "typedoc"
   },
-  "gitHead": "f215995ab4adeac4c58171739261a15cbba9e82b"
+  "gitHead": "dcac54f8adf77240e293c93d224a0ce9fd8142a9"
 }