@vibedash/client 0.1.0 → 0.2.0

package/dist/duckdb-singleton.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lazy-initialized DuckDB-WASM singleton.
+ *
+ * Only loaded when the first cached query is detected — dashboards that don't
+ * use caching never pay the bundle cost (~200KB JS + 4MB WASM).
+ */
+interface DuckDBInstance {
+    query: (sql: string) => Promise<Record<string, unknown>[]>;
+    loadParquet: (name: string, url: string) => Promise<void>;
+    isTableLoaded: (name: string) => boolean;
+}
+export declare function getDuckDB(): Promise<DuckDBInstance>;
+export {};

package/dist/duckdb-singleton.js

@@ -0,0 +1,44 @@
+/**
+ * Lazy-initialized DuckDB-WASM singleton.
+ *
+ * Only loaded when the first cached query is detected — dashboards that don't
+ * use caching never pay the bundle cost (~200KB JS + 4MB WASM).
+ */
+let dbPromise = null;
+export function getDuckDB() {
+    if (!dbPromise) {
+        dbPromise = initDuckDB();
+    }
+    return dbPromise;
+}
+async function initDuckDB() {
+    const duckdb = await import("@duckdb/duckdb-wasm");
+    // Use CDN-hosted bundles (browser caches these)
+    const JSDELIVR_BUNDLES = duckdb.getJsDelivrBundles();
+    const bundle = await duckdb.selectBundle(JSDELIVR_BUNDLES);
+    const worker = new Worker(bundle.mainWorker);
+    const logger = new duckdb.ConsoleLogger();
+    const db = new duckdb.AsyncDuckDB(logger, worker);
+    await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
+    const conn = await db.connect();
+    const loadedTables = new Set();
+    return {
+        async query(sql) {
+            const result = await conn.query(sql);
+            return result.toArray().map((row) => row.toJSON());
+        },
+        async loadParquet(name, url) {
+            if (loadedTables.has(name))
+                return;
+            // Fetch the Parquet file and register it
+            const response = await fetch(url);
+            const buffer = await response.arrayBuffer();
+            await db.registerFileBuffer(`${name}.parquet`, new Uint8Array(buffer));
+            await conn.query(`CREATE TABLE IF NOT EXISTS "${name}" AS SELECT * FROM read_parquet('${name}.parquet')`);
+            loadedTables.add(name);
+        },
+        isTableLoaded(name) {
+            return loadedTables.has(name);
+        },
+    };
+}

package/dist/types.d.ts

@@ -17,6 +17,10 @@ export interface UseQueryResult<T = Record<string, unknown>[]> {
     loading: boolean;
     /** Error message if the query failed */
     error: string | null;
-    /** Re-run the query manually */
+    /** Re-run the query manually (forces cache refresh if cached) */
     refetch: () => Promise<void>;
+    /** When the cached data was last refreshed (undefined if not cached) */
+    cachedAt?: Date;
+    /** Run SQL locally against cached data via DuckDB-WASM (undefined if not cached) */
+    query?: (sql: string) => Promise<Record<string, unknown>[]>;
 }

package/dist/use-query.d.ts

@@ -2,13 +2,23 @@ import type { UseQueryOptions, UseQueryResult } from "./types";
 /**
  * Fetches data from a registered query by name.
  *
+ * If the dashboard has a cache TTL set in the Hub, data is served from a cached
+ * Parquet file and loaded into DuckDB-WASM in the browser. This enables instant
+ * client-side SQL filtering via the returned `query()` function.
+ *
+ * If no cache TTL is set, data comes from BigQuery live (existing behavior).
+ *
  * Usage:
  * ```tsx
- * const { data, loading, error } = useQuery("monthly_revenue");
- * ```
+ * const { data, query, loading, cachedAt } = useQuery("monthly_revenue");
  *
- * The query must be registered at deploy time. The browser never sends raw SQL —
- * only the query name. Vibe Dash looks up the SQL server-side, runs it against
- * your BigQuery warehouse using stored credentials, and returns the results.
+ * // All rows (works with or without cache)
+ * const allRows = data;
+ *
+ * // Filter locally (only when cached)
+ * if (query) {
+ *   const filtered = await query("SELECT * FROM monthly_revenue WHERE region = 'US'");
+ * }
+ * ```
  */
 export declare function useQuery<T = Record<string, unknown>[]>(queryName: string, options?: UseQueryOptions): UseQueryResult<T>;

package/dist/use-query.js

@@ -1,24 +1,38 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useEffect, useCallback, useRef } from "react";
 import { useVibeDash } from "./provider";
 /**
  * Fetches data from a registered query by name.
  *
+ * If the dashboard has a cache TTL set in the Hub, data is served from a cached
+ * Parquet file and loaded into DuckDB-WASM in the browser. This enables instant
+ * client-side SQL filtering via the returned `query()` function.
+ *
+ * If no cache TTL is set, data comes from BigQuery live (existing behavior).
+ *
  * Usage:
  * ```tsx
- * const { data, loading, error } = useQuery("monthly_revenue");
- * ```
+ * const { data, query, loading, cachedAt } = useQuery("monthly_revenue");
+ *
+ * // All rows (works with or without cache)
+ * const allRows = data;
  *
- * The query must be registered at deploy time. The browser never sends raw SQL —
- * only the query name. Vibe Dash looks up the SQL server-side, runs it against
- * your BigQuery warehouse using stored credentials, and returns the results.
+ * // Filter locally (only when cached)
+ * if (query) {
+ *   const filtered = await query("SELECT * FROM monthly_revenue WHERE region = 'US'");
+ * }
+ * ```
  */
 export function useQuery(queryName, options) {
     const { apiUrl, projectSlug, apiKey } = useVibeDash();
     const [data, setData] = useState(null);
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
+    const [cachedAt, setCachedAt] = useState(undefined);
+    // Store the query function in a ref so it's stable
+    const queryFnRef = useRef(undefined);
+    const [queryReady, setQueryReady] = useState(false);
     const enabled = options?.enabled !== false;
-    const fetchData = useCallback(async () => {
+    const fetchData = useCallback(async (forceRefresh = false) => {
         setLoading(true);
         setError(null);
         try {
@@ -35,6 +49,7 @@ export function useQuery(queryName, options) {
                 body: JSON.stringify({
                     project_slug: projectSlug,
                     query_name: queryName,
+                    force_refresh: forceRefresh,
                 }),
             });
             if (!res.ok) {
@@ -42,7 +57,29 @@ export function useQuery(queryName, options) {
                 throw new Error(body.error || `Query failed with status ${res.status}`);
             }
             const body = await res.json();
-            setData(body.data);
+            if (body.cached && body.parquet_url) {
+                // Cached response — load Parquet into DuckDB-WASM
+                const { getDuckDB } = await import("./duckdb-singleton");
+                const db = await getDuckDB();
+                // Force reload on refresh, otherwise reuse if already loaded
+                if (forceRefresh || !db.isTableLoaded(queryName)) {
+                    await db.loadParquet(queryName, body.parquet_url);
+                }
+                // Read all rows as default data
+                const allRows = await db.query(`SELECT * FROM "${queryName}"`);
+                setData(allRows);
+                setCachedAt(new Date(body.cached_at));
+                // Expose local SQL query function
+                queryFnRef.current = (sql) => db.query(sql);
+                setQueryReady(true);
+            }
+            else {
+                // Live response — standard JSON data
+                setData(body.data);
+                setCachedAt(undefined);
+                queryFnRef.current = undefined;
+                setQueryReady(false);
+            }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : "Failed to fetch data";
@@ -51,11 +88,18 @@ export function useQuery(queryName, options) {
         finally {
             setLoading(false);
         }
-    }, [apiUrl, projectSlug, queryName]);
+    }, [apiUrl, projectSlug, queryName, apiKey]);
     useEffect(() => {
         if (enabled) {
             fetchData();
         }
     }, [enabled, fetchData]);
-    return { data, loading, error, refetch: fetchData };
+    return {
+        data,
+        loading,
+        error,
+        cachedAt,
+        query: queryReady ? queryFnRef.current : undefined,
+        refetch: () => fetchData(true),
+    };
 }

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "@vibedash/client",
-  "version": "0.1.0",
-  "description": "React hooks for Vibe Dash dashboards — useQuery() for data fetching",
+  "version": "0.2.0",
+  "description": "React hooks for Vibe Dash dashboards — useQuery() with optional DuckDB-WASM caching",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch"
   },
   "peerDependencies": {
+    "@duckdb/duckdb-wasm": ">=1.28.0",
     "react": ">=18"
   },
+  "peerDependenciesMeta": {
+    "@duckdb/duckdb-wasm": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@duckdb/duckdb-wasm": "^1.33.1-dev20.0",
     "@types/react": "^19",
     "react": "^19",
     "typescript": "^5"