@vibedash/client 0.1.0 → 0.3.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, forceReload?: boolean) => Promise<void>;
+    isTableLoaded: (name: string) => boolean;
+}
+export declare function getDuckDB(): Promise<DuckDBInstance>;
+export {};

package/dist/duckdb-singleton.js

@@ -0,0 +1,48 @@
+/**
+ * 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, forceReload = false) {
+            if (loadedTables.has(name) && !forceReload)
+                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));
+            // Drop existing table on force reload so we pick up the new data
+            if (forceReload && loadedTables.has(name)) {
+                await conn.query(`DROP TABLE IF EXISTS "${name}"`);
+            }
+            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/index.d.ts

@@ -1,3 +1,3 @@
 export { useQuery } from "./use-query";
-export { VibeDashProvider, useVibeDash } from "./provider";
+export { VibeDashProvider, useVibeDash, useRefreshAll } from "./provider";
 export type { UseQueryOptions, UseQueryResult, VibeDashConfig } from "./types";

package/dist/index.js

@@ -1,2 +1,2 @@
 export { useQuery } from "./use-query";
-export { VibeDashProvider, useVibeDash } from "./provider";
+export { VibeDashProvider, useVibeDash, useRefreshAll } from "./provider";

package/dist/provider.d.ts

@@ -1,5 +1,13 @@
 import type { VibeDashConfig } from "./types";
-export declare function VibeDashProvider({ apiUrl, projectSlug, apiKey, children, }: VibeDashConfig & {
+type RefetchFn = () => Promise<void>;
+interface VibeDashContextValue extends VibeDashConfig {
+    registerQuery: (name: string, fn: RefetchFn, cachedAt: Date | null) => void;
+    unregisterQuery: (name: string) => void;
+    refreshAll: () => Promise<void>;
+}
+export declare function VibeDashProvider({ apiUrl, projectSlug, dashboardSlug, apiKey, children, }: VibeDashConfig & {
     children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function useVibeDash(): VibeDashConfig;
+export declare function useVibeDash(): VibeDashContextValue;
+export declare function useRefreshAll(): () => Promise<void>;
+export {};

package/dist/provider.js

@@ -1,14 +1,103 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext } from "react";
+import { createContext, useContext, useCallback, useRef, useEffect, useState, } from "react";
 const VibeDashContext = createContext(null);
-export function VibeDashProvider({ apiUrl, projectSlug, apiKey, children, }) {
-    return (_jsx(VibeDashContext.Provider, { value: { apiUrl, projectSlug, apiKey }, children: children }));
+const POLL_INTERVAL_ACTIVE = 30000; // 30s when caching is on
+const POLL_INTERVAL_IDLE = 300000; // 5min when caching is off
+export function VibeDashProvider({ apiUrl, projectSlug, dashboardSlug, apiKey, children, }) {
+    const queryMap = useRef(new Map());
+    const [pollInterval, setPollInterval] = useState(POLL_INTERVAL_IDLE);
+    const registerQuery = useCallback((name, fn, cachedAt) => {
+        queryMap.current.set(name, { refetch: fn, cachedAt });
+    }, []);
+    const unregisterQuery = useCallback((name) => {
+        queryMap.current.delete(name);
+    }, []);
+    const refreshAll = useCallback(async () => {
+        const fns = Array.from(queryMap.current.values()).map((e) => e.refetch);
+        await Promise.allSettled(fns.map((fn) => fn()));
+    }, []);
+    // Auto-polling for live cache updates
+    useEffect(() => {
+        if (!dashboardSlug)
+            return;
+        let timeoutId;
+        let cancelled = false;
+        async function poll() {
+            if (cancelled)
+                return;
+            try {
+                const headers = {
+                    "Content-Type": "application/json",
+                };
+                if (apiKey) {
+                    headers["Authorization"] = `Bearer ${apiKey}`;
+                }
+                const res = await fetch(`${apiUrl}/query/status`, {
+                    method: "POST",
+                    headers,
+                    credentials: apiKey ? "omit" : "include",
+                    body: JSON.stringify({
+                        project_slug: projectSlug,
+                        dashboard_slug: dashboardSlug,
+                    }),
+                });
+                if (!res.ok)
+                    return;
+                const status = await res.json();
+                // Adjust poll interval based on cache mode
+                const newInterval = status.cache_mode && status.cache_mode !== "none"
+                    ? POLL_INTERVAL_ACTIVE
+                    : POLL_INTERVAL_IDLE;
+                setPollInterval(newInterval);
+                // Check for stale queries and refetch
+                if (status.queries) {
+                    for (const [queryName, info] of Object.entries(status.queries)) {
+                        const entry = queryMap.current.get(queryName);
+                        if (!entry || !info.cached_at)
+                            continue;
+                        const serverCachedAt = new Date(info.cached_at);
+                        const clientCachedAt = entry.cachedAt;
+                        // Server has newer data — trigger refetch
+                        if (!clientCachedAt ||
+                            serverCachedAt.getTime() > clientCachedAt.getTime()) {
+                            entry.refetch();
+                        }
+                    }
+                }
+            }
+            catch {
+                // Silently fail — will retry next interval
+            }
+            if (!cancelled) {
+                timeoutId = setTimeout(poll, pollInterval);
+            }
+        }
+        // Start first poll after a short delay (let queries mount first)
+        timeoutId = setTimeout(poll, 5000);
+        return () => {
+            cancelled = true;
+            clearTimeout(timeoutId);
+        };
+    }, [apiUrl, projectSlug, dashboardSlug, apiKey, pollInterval]);
+    return (_jsx(VibeDashContext.Provider, { value: {
+            apiUrl,
+            projectSlug,
+            dashboardSlug,
+            apiKey,
+            registerQuery,
+            unregisterQuery,
+            refreshAll,
+        }, children: children }));
 }
 export function useVibeDash() {
     const ctx = useContext(VibeDashContext);
     if (!ctx) {
         throw new Error("useVibeDash must be used within a <VibeDashProvider>. " +
-            "Wrap your app in <VibeDashProvider apiUrl=\"...\" projectSlug=\"...\">.");
+            'Wrap your app in <VibeDashProvider apiUrl="..." projectSlug="...">.');
     }
     return ctx;
 }
+export function useRefreshAll() {
+    const { refreshAll } = useVibeDash();
+    return refreshAll;
+}

package/dist/types.d.ts

@@ -3,6 +3,8 @@ export interface VibeDashConfig {
     apiUrl: string;
     /** The project slug (e.g. "data-man") */
     projectSlug: string;
+    /** The dashboard slug — enables auto-polling for live cache updates */
+    dashboardSlug?: string;
     /** API key for authentication (used in local dev, read from env) */
     apiKey?: string;
 }
@@ -17,6 +19,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,26 @@ 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).
+ *
+ * Data stays fresh automatically — when the Hub refreshes the cache in the
+ * background, the provider detects the change and triggers a reload.
+ *
  * 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 declare function useQuery<T = Record<string, unknown>[]>(queryName: string, options?: UseQueryOptions): UseQueryResult<T>;

package/dist/use-query.js

@@ -1,24 +1,41 @@
-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).
+ *
+ * Data stays fresh automatically — when the Hub refreshes the cache in the
+ * background, the provider detects the change and triggers a reload.
+ *
  * 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 { apiUrl, projectSlug, apiKey, registerQuery, unregisterQuery } = 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 +52,7 @@ export function useQuery(queryName, options) {
                 body: JSON.stringify({
                     project_slug: projectSlug,
                     query_name: queryName,
+                    force_refresh: forceRefresh,
                 }),
             });
             if (!res.ok) {
@@ -42,7 +60,30 @@ 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, forceRefresh);
+                }
+                // Read all rows as default data
+                const allRows = await db.query(`SELECT * FROM "${queryName}"`);
+                setData(allRows);
+                const newCachedAt = new Date(body.cached_at);
+                setCachedAt(newCachedAt);
+                // 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 +92,28 @@ export function useQuery(queryName, options) {
         finally {
             setLoading(false);
         }
-    }, [apiUrl, projectSlug, queryName]);
+    }, [apiUrl, projectSlug, queryName, apiKey]);
+    // Register this query by name so the provider can:
+    // 1. Call refetch via useRefreshAll()
+    // 2. Detect stale data via auto-polling and trigger refetch
+    const refetchFn = useCallback(() => fetchData(true), [fetchData]);
+    useEffect(() => {
+        if (enabled) {
+            registerQuery(queryName, refetchFn, cachedAt ?? null);
+            return () => unregisterQuery(queryName);
+        }
+    }, [enabled, queryName, refetchFn, cachedAt, registerQuery, unregisterQuery]);
     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.3.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"