@fusedio/widget-sdk 0.1.0

package/dist/hooks/use-duckdb-sql.js

@@ -0,0 +1,558 @@
+/**
+ * DuckDB SQL execution against UDF Parquet outputs.
+ *
+ * Two hooks layered together:
+ *   - `useDuckDbSqlQueryPreprocessing` parses placeholders, subscribes to
+ *     `$param` / form values, calls the bridge to register UDFs in DuckDB
+ *     VFS, signs any `s3://`/`gs://`/`fd://` URL literals, and returns the
+ *     final ready-to-run SQL string.
+ *   - `useDuckDbSqlQuery` consumes that processed SQL, runs it via the
+ *     bridge, and surfaces `{ rows, columns, loading, error, refetch }`.
+ *
+ * All state-storage details (Jotai atoms, DuckDB wasm, fetcher) live on
+ * the host side via the bridge. Both hooks work identically in the
+ * workbench, the catalog-template test harness, or any other host.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useFusedWidgetBridge } from "../bridge";
+import { useFormParams } from "../form";
+import { useJsonUiLog } from "./use-json-ui-log";
+import { useJsonUiEdgeAnimation } from "./use-json-ui-edge-animation";
+import { useCanvasParams } from "./use-canvas-params";
+import { computePlaceholderKey, extractSignableUrls, extractSqlParams, parseSqlUdfPlaceholders, resolveOverrideValue, rewriteSignedUrls, substituteSqlParams, getDollarRefName, } from "../utils/sql-placeholders";
+const DEFAULT_MAX_ROWS = 500;
+const EMPTY_ROWS = Object.freeze([]);
+const EMPTY_COLUMNS = Object.freeze([]);
+function appendLimitIfMissing(sql, maxRows) {
+    if (/\bLIMIT\b/i.test(sql))
+        return sql;
+    const trimmed = sql.trimEnd();
+    const withoutTrailingSemicolon = trimmed.endsWith(";")
+        ? trimmed.slice(0, -1)
+        : trimmed;
+    return `${withoutTrailingSemicolon} LIMIT ${maxRows}`;
+}
+function escapeSqlIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+function buildProcessedSql(sql, resolved, fileNameMap, sourceOverrides, sqlParamValues, maxRows) {
+    // When the entire sql prop is a single $param (e.g. "$sql_query"),
+    // use the raw param value directly — it's already a complete SQL string.
+    const singleParam = sql.match(/^\$([a-zA-Z_][a-zA-Z0-9_]*)$/);
+    if (singleParam) {
+        const val = sqlParamValues[singleParam[1]];
+        return val == null ? "" : appendLimitIfMissing(String(val), maxRows);
+    }
+    // Walk right-to-left so earlier offsets stay valid as we splice.
+    let processedSql = sql;
+    for (let i = resolved.length - 1; i >= 0; i--) {
+        const { raw, key, resolvedOverrides } = resolved[i];
+        const isBase = resolvedOverrides === null;
+        const sourceOverride = isBase && sourceOverrides ? sourceOverrides[raw.name] : undefined;
+        let replacement;
+        if (sourceOverride) {
+            replacement = escapeSqlIdentifier(sourceOverride.relationName);
+        }
+        else {
+            const fileName = fileNameMap.get(key) ?? `${raw.name}.parquet`;
+            replacement = `'${fileName}'`;
+        }
+        processedSql =
+            processedSql.slice(0, raw.start) +
+                replacement +
+                processedSql.slice(raw.end);
+    }
+    processedSql = appendLimitIfMissing(processedSql, maxRows);
+    return substituteSqlParams(processedSql, sqlParamValues);
+}
+/**
+ * Preprocess SQL: resolve placeholders, register UDFs via the bridge,
+ * substitute params, sign URLs, append LIMIT. Returns the prepared SQL.
+ */
+export function useDuckDbSqlQueryPreprocessing({ sql, enabled = true, maxRows = DEFAULT_MAX_ROWS, sourceOverrides, }) {
+    const bridge = useFusedWidgetBridge();
+    const { startLoading: startEdgeLoading, stopLoading: stopEdgeLoading } = useJsonUiEdgeAnimation();
+    const { log } = useJsonUiLog();
+    const [processedSql, setProcessedSql] = useState("");
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [fetchKey, setFetchKey] = useState(0);
+    const sourcePlaceholders = useMemo(() => {
+        if (!sql)
+            return [];
+        return parseSqlUdfPlaceholders(sql);
+    }, [sql]);
+    // Skip placeholders that have a sourceOverride active (workbench-only path).
+    const placeholdersAfterOverride = useMemo(() => {
+        if (!sourceOverrides)
+            return sourcePlaceholders;
+        return sourcePlaceholders.filter((p) => p.overrides !== null || !sourceOverrides[p.name]);
+    }, [sourcePlaceholders, sourceOverrides]);
+    // Override values may reference $params — collect those names so we can
+    // subscribe to the same canvas/form param map the SQL body uses.
+    const overrideParamNames = useMemo(() => {
+        const set = new Set();
+        for (const p of placeholdersAfterOverride) {
+            if (!p.overrides)
+                continue;
+            for (const v of Object.values(p.overrides)) {
+                const name = getDollarRefName(v);
+                if (name)
+                    set.add(name);
+            }
+        }
+        return Array.from(set);
+    }, [placeholdersAfterOverride]);
+    const sqlParamNames = useMemo(() => {
+        if (!sql)
+            return [];
+        return extractSqlParams(sql);
+    }, [sql]);
+    // Subscribe to canvas + form params for both the SQL body and override refs.
+    const allParamNames = useMemo(() => {
+        const seen = new Set();
+        const out = [];
+        for (const n of sqlParamNames) {
+            if (seen.has(n))
+                continue;
+            seen.add(n);
+            out.push(n);
+        }
+        for (const n of overrideParamNames) {
+            if (seen.has(n))
+                continue;
+            seen.add(n);
+            out.push(n);
+        }
+        return out;
+    }, [sqlParamNames, overrideParamNames]);
+    const canvasParamValues = useCanvasParams(allParamNames);
+    const { inForm, values: formParamValues } = useFormParams(allParamNames);
+    const sqlParamValues = useMemo(() => inForm ? { ...canvasParamValues, ...formParamValues } : canvasParamValues, [inForm, canvasParamValues, formParamValues]);
+    const resolvedPlaceholders = useMemo(() => {
+        return placeholdersAfterOverride.map((p) => {
+            if (!p.overrides) {
+                return {
+                    raw: p,
+                    key: p.name,
+                    resolvedOverrides: null,
+                    unresolved: false,
+                };
+            }
+            const resolvedOverrides = {};
+            let unresolved = false;
+            for (const [paramKey, rawValue] of Object.entries(p.overrides)) {
+                const r = resolveOverrideValue(rawValue, sqlParamValues);
+                if (r.unresolved)
+                    unresolved = true;
+                resolvedOverrides[paramKey] = r.value;
+            }
+            return {
+                raw: p,
+                key: computePlaceholderKey(p.name, resolvedOverrides),
+                resolvedOverrides,
+                unresolved,
+            };
+        });
+    }, [placeholdersAfterOverride, sqlParamValues]);
+    // Deduplicate refs we need to pass to the bridge for VFS registration.
+    const vfsRefs = useMemo(() => {
+        const seen = new Set();
+        const out = [];
+        for (const rp of resolvedPlaceholders) {
+            if (rp.unresolved)
+                continue;
+            if (seen.has(rp.key))
+                continue;
+            seen.add(rp.key);
+            out.push({
+                name: rp.raw.name,
+                key: rp.key,
+                overrides: rp.resolvedOverrides ?? undefined,
+            });
+        }
+        return out;
+    }, [resolvedPlaceholders]);
+    // Stable key for the refs list — avoids re-running the resolve effect when
+    // the underlying refs are structurally identical.
+    const refsKey = useMemo(() => {
+        return vfsRefs
+            .map((r) => `${r.key}|${r.name}|${r.overrides
+            ? Object.entries(r.overrides)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([k, v]) => `${k}=${v}`)
+                .join(",")
+            : ""}`)
+            .join("\n");
+    }, [vfsRefs]);
+    const refetch = useCallback(() => {
+        setFetchKey((k) => k + 1);
+    }, []);
+    // Subscribe to UDF output changes for every referenced UDF — `resolveVfsFilenames`
+    // doesn't auto-rerun when a UDF re-executes, so we trigger a refetch.
+    useEffect(() => {
+        if (!enabled || vfsRefs.length === 0)
+            return;
+        const unsubs = vfsRefs.map((ref) => bridge.udfs.subscribeOutput(ref.name, () => {
+            setFetchKey((k) => k + 1);
+        }));
+        return () => {
+            unsubs.forEach((u) => u());
+        };
+    }, [bridge, enabled, vfsRefs]);
+    // Edge animation mirrors loading.
+    useEffect(() => {
+        if (loading)
+            startEdgeLoading();
+        else
+            stopEdgeLoading();
+    }, [loading, startEdgeLoading, stopEdgeLoading]);
+    // Watch for sourceOverride errors / loading so the preprocessing reflects them.
+    const sourceOverrideError = useMemo(() => {
+        if (!sourceOverrides)
+            return null;
+        for (const p of sourcePlaceholders) {
+            if (p.overrides !== null)
+                continue;
+            const src = sourceOverrides[p.name];
+            if (src?.error)
+                return src.error;
+        }
+        return null;
+    }, [sourcePlaceholders, sourceOverrides]);
+    const sourceOverrideLoading = useMemo(() => {
+        if (!sourceOverrides)
+            return false;
+        return sourcePlaceholders.some((p) => p.overrides === null && sourceOverrides[p.name]?.loading);
+    }, [sourcePlaceholders, sourceOverrides]);
+    const hasUnresolvedOverride = resolvedPlaceholders.some((rp) => rp.unresolved);
+    useEffect(() => {
+        if (!enabled || !sql) {
+            setProcessedSql("");
+            setLoading(false);
+            setError(null);
+            return;
+        }
+        if (sourceOverrideError) {
+            setProcessedSql("");
+            setError(sourceOverrideError);
+            setLoading(false);
+            log(`SQL preprocessing: ${sourceOverrideError}`, "error");
+            return;
+        }
+        if (sourceOverrideLoading || hasUnresolvedOverride) {
+            setProcessedSql("");
+            setError(null);
+            setLoading(true);
+            return;
+        }
+        let cancelled = false;
+        setLoading(true);
+        setError(null);
+        (async () => {
+            let fileNameMap = new Map();
+            let registrationErrorMap;
+            if (vfsRefs.length > 0) {
+                try {
+                    const result = await bridge.sql.resolveVfsFilenames(vfsRefs);
+                    if (cancelled)
+                        return;
+                    if (result instanceof Map) {
+                        // Legacy shape — names → filenames. Build a key-keyed map.
+                        for (const rp of resolvedPlaceholders) {
+                            if (rp.resolvedOverrides)
+                                continue; // legacy hosts can't handle overrides
+                            const fn = result.get(rp.raw.name);
+                            if (fn)
+                                fileNameMap.set(rp.key, fn);
+                        }
+                    }
+                    else {
+                        fileNameMap = result.filenames;
+                        registrationErrorMap = result.errors;
+                    }
+                }
+                catch (e) {
+                    if (cancelled)
+                        return;
+                    const msg = e instanceof Error
+                        ? e.message
+                        : typeof e === "string"
+                            ? e
+                            : "VFS registration failed";
+                    setProcessedSql("");
+                    setError(msg);
+                    setLoading(false);
+                    log(`SQL preprocessing: ${msg}`, "error");
+                    return;
+                }
+            }
+            // Surface any per-key registration error.
+            if (registrationErrorMap) {
+                for (const rp of resolvedPlaceholders) {
+                    const err = registrationErrorMap.get(rp.key);
+                    if (err) {
+                        if (cancelled)
+                            return;
+                        setProcessedSql("");
+                        setError(err);
+                        setLoading(false);
+                        log(`SQL preprocessing: ${err}`, "error");
+                        return;
+                    }
+                }
+            }
+            // Every non-unresolved placeholder should now have a filename (or use a sourceOverride).
+            for (const rp of resolvedPlaceholders) {
+                if (rp.unresolved)
+                    continue;
+                const isBase = rp.resolvedOverrides === null;
+                const hasSourceOverride = isBase && sourceOverrides?.[rp.raw.name] !== undefined;
+                if (hasSourceOverride)
+                    continue;
+                if (!fileNameMap.has(rp.key)) {
+                    if (cancelled)
+                        return;
+                    // Bridge didn't return a filename; treat as still loading.
+                    setProcessedSql("");
+                    setError(null);
+                    setLoading(true);
+                    return;
+                }
+            }
+            let nextProcessedSql;
+            try {
+                nextProcessedSql = buildProcessedSql(sql, resolvedPlaceholders, fileNameMap, sourceOverrides, sqlParamValues, maxRows);
+            }
+            catch (e) {
+                if (cancelled)
+                    return;
+                const msg = e instanceof Error
+                    ? e.message
+                    : typeof e === "string"
+                        ? e
+                        : "SQL preprocessing failed";
+                setProcessedSql("");
+                setError(msg);
+                setLoading(false);
+                log(`SQL preprocessing failed: ${msg}`, "error");
+                return;
+            }
+            const urls = extractSignableUrls(nextProcessedSql);
+            if (urls.length === 0) {
+                if (cancelled)
+                    return;
+                setProcessedSql(nextProcessedSql);
+                setError(null);
+                setLoading(false);
+                log("SQL preprocessing completed");
+                return;
+            }
+            try {
+                const signedMap = {};
+                const signed = await Promise.all(urls.map((u) => bridge.signUrl(u)));
+                if (cancelled)
+                    return;
+                urls.forEach((u, i) => {
+                    signedMap[u] = signed[i].signed;
+                });
+                const signedSql = rewriteSignedUrls(nextProcessedSql, signedMap);
+                setProcessedSql(signedSql);
+                setError(null);
+                setLoading(false);
+                log("SQL preprocessing completed");
+            }
+            catch (e) {
+                if (cancelled)
+                    return;
+                const msg = e instanceof Error
+                    ? e.message
+                    : typeof e === "string"
+                        ? e
+                        : "URL signing failed";
+                setProcessedSql("");
+                setError(msg);
+                setLoading(false);
+                log(`SQL preprocessing failed: ${msg}`, "error");
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        bridge,
+        enabled,
+        sql,
+        refsKey,
+        resolvedPlaceholders,
+        sqlParamValues,
+        sourceOverrides,
+        sourceOverrideError,
+        sourceOverrideLoading,
+        hasUnresolvedOverride,
+        maxRows,
+        fetchKey,
+        log,
+        vfsRefs,
+    ]);
+    return { processedSql, loading, error, refetch };
+}
+/**
+ * Execute a DuckDB SQL query against UDF Parquet outputs. Uses
+ * `useDuckDbSqlQueryPreprocessing` to prepare the SQL string, then runs
+ * it via the bridge.
+ */
+export function useDuckDbSqlQuery({ sql, enabled = true, maxRows = DEFAULT_MAX_ROWS, sourceOverrides, }) {
+    const bridge = useFusedWidgetBridge();
+    const { startLoading: startEdgeLoading, stopLoading: stopEdgeLoading } = useJsonUiEdgeAnimation();
+    const { log } = useJsonUiLog();
+    const [rows, setRows] = useState(EMPTY_ROWS);
+    const [columns, setColumns] = useState(EMPTY_COLUMNS);
+    const [queryLoading, setQueryLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [fetchKey, setFetchKey] = useState(0);
+    const { processedSql, loading: preprocessingLoading, error: preprocessingError, refetch: refetchPreprocessing, } = useDuckDbSqlQueryPreprocessing({
+        sql,
+        enabled,
+        maxRows,
+        sourceOverrides,
+    });
+    // Bridges the single-frame gap between preprocessing completing and the
+    // query effect starting — keeps `loading` true through that frame.
+    const consumedSqlRef = useRef("");
+    const awaitingExecution = enabled &&
+        !!sql &&
+        !!processedSql &&
+        !preprocessingLoading &&
+        !preprocessingError &&
+        processedSql !== consumedSqlRef.current;
+    const loading = preprocessingLoading || queryLoading || awaitingExecution;
+    useEffect(() => {
+        if (loading)
+            startEdgeLoading();
+        else
+            stopEdgeLoading();
+    }, [loading, startEdgeLoading, stopEdgeLoading]);
+    const refetch = useCallback(() => {
+        consumedSqlRef.current = "";
+        refetchPreprocessing();
+        setFetchKey((k) => k + 1);
+    }, [refetchPreprocessing]);
+    useEffect(() => {
+        if (!enabled || !sql) {
+            consumedSqlRef.current = "";
+            setRows(EMPTY_ROWS);
+            setColumns(EMPTY_COLUMNS);
+            setQueryLoading(false);
+            setError(null);
+            return;
+        }
+        if (preprocessingError) {
+            consumedSqlRef.current = "";
+            setError(preprocessingError);
+            setRows(EMPTY_ROWS);
+            setColumns(EMPTY_COLUMNS);
+            setQueryLoading(false);
+            return;
+        }
+        if (preprocessingLoading || !processedSql) {
+            consumedSqlRef.current = "";
+            setQueryLoading(false);
+            return;
+        }
+        let cancelled = false;
+        const controller = new AbortController();
+        consumedSqlRef.current = processedSql;
+        setQueryLoading(true);
+        setError(null);
+        const truncatedSql = processedSql.length > 120
+            ? processedSql.slice(0, 120) + "…"
+            : processedSql;
+        log(`SQL query started: ${truncatedSql}`);
+        const t0 = performance.now();
+        bridge.sql.query(processedSql, { signal: controller.signal }).then((result) => {
+            if (cancelled)
+                return;
+            const elapsed = Math.round(performance.now() - t0);
+            if (result.error) {
+                setRows(EMPTY_ROWS);
+                setColumns(EMPTY_COLUMNS);
+                setError(result.error);
+                setQueryLoading(false);
+                log(`SQL failed (${elapsed}ms): ${result.error}`, "error");
+                return;
+            }
+            setRows(result.rows.length === 0 ? EMPTY_ROWS : result.rows);
+            setColumns(result.columns);
+            setError(null);
+            setQueryLoading(false);
+            log(`SQL completed: ${result.rows.length} row${result.rows.length !== 1 ? "s" : ""} in ${elapsed}ms`);
+        }, (e) => {
+            if (cancelled)
+                return;
+            if (e?.name === "AbortError")
+                return;
+            const elapsed = Math.round(performance.now() - t0);
+            const msg = e instanceof Error
+                ? e.message
+                : typeof e === "string"
+                    ? e
+                    : "SQL query failed";
+            setError(msg);
+            setRows(EMPTY_ROWS);
+            setColumns(EMPTY_COLUMNS);
+            setQueryLoading(false);
+            log(`SQL failed (${elapsed}ms): ${msg}`, "error");
+        });
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [
+        bridge,
+        enabled,
+        sql,
+        processedSql,
+        preprocessingLoading,
+        preprocessingError,
+        fetchKey,
+        log,
+    ]);
+    return { rows, columns, loading, error, refetch };
+}
+/**
+ * Resolve UDF names to VFS filenames, registering them in DuckDB if needed.
+ * Exposed for advanced use cases (e.g. building your own query string).
+ */
+export function useVfsRegistration(udfNames, enabled = true) {
+    const bridge = useFusedWidgetBridge();
+    const [state, setState] = useState({ filenames: new Map(), loading: false });
+    const namesKey = useMemo(() => udfNames.slice().sort().join("|"), [udfNames]);
+    useEffect(() => {
+        if (!enabled || udfNames.length === 0) {
+            setState({ filenames: new Map(), loading: false });
+            return;
+        }
+        let cancelled = false;
+        setState((prev) => ({ ...prev, loading: true, error: undefined }));
+        bridge.sql.resolveVfsFilenames(udfNames).then((result) => {
+            if (cancelled)
+                return;
+            const filenames = result instanceof Map ? result : result.filenames;
+            setState({ filenames, loading: false });
+        }, (err) => {
+            if (cancelled)
+                return;
+            setState({
+                filenames: new Map(),
+                loading: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [bridge, namesKey, enabled]);
+    return state;
+}

package/dist/hooks/use-fused-param.d.ts

@@ -0,0 +1,40 @@
+import type { UseFusedParamOptions, UseFusedParamReturn } from "../types";
+/**
+ * Two-way bind a component to a named canvas parameter.
+ *
+ * When another node broadcasts a param value (e.g. a map click, a dropdown
+ * selection from upstream), this hook receives it and updates `value`. When
+ * the user interacts locally, `setValue()` debounces and broadcasts back so
+ * connected UDF nodes re-run with the new value.
+ *
+ * Form integration: when this component is rendered inside a built-in Form,
+ * the live form-field value shadows the canvas value so siblings react
+ * before the form is submitted (form values are never broadcast to the
+ * canvas until submit).
+ *
+ * Works as plain local state if `param` is undefined or empty.
+ *
+ * Requires: a `FusedWidgetBridgeContext.Provider` ancestor. The workbench's
+ * `JsonUiProvider` provides one; tests use `createTestBridge()`.
+ *
+ * @example — number counter
+ * const { value, setValue } = useFusedParam({ param: "count", defaultValue: 0 });
+ * return <button onClick={() => setValue(value + 1)}>{value}</button>;
+ *
+ * @example — typed array param
+ * const { value, setValue } = useFusedParam({
+ *   param: "bounds",
+ *   defaultValue: [-74, 40, -73, 41] as [number, number, number, number],
+ *   validate: (v): v is [number, number, number, number] =>
+ *     Array.isArray(v) && v.length === 4 && v.every(n => typeof n === "number"),
+ * });
+ *
+ * @example — broadcast immediately on mouseup (bypass debounce)
+ * const { setValue, broadcastNow } = useFusedParam({ param: "hue", defaultValue: 0 });
+ * <input type="range" onChange={e => setValue(+e.target.value)} onMouseUp={broadcastNow} />
+ *
+ * @example — clear button
+ * const { clearValue } = useFusedParam({ param: "selection", defaultValue: null });
+ * <button onClick={() => clearValue(null)}>Reset</button>
+ */
+export declare function useFusedParam<T>({ param, debounceMs, readOnly, defaultValue, broadcastDefaultValue, validate, preprocess, }: UseFusedParamOptions<T>): UseFusedParamReturn<T>;