@duckdb/react-duckdb 1.13.1-dev260.0

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "@duckdb/react-duckdb",
+    "version": "1.13.1-dev260.0",
+    "description": "React components for DuckDB-Wasm",
+    "license": "MPL-2.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/duckdb/duckdb-wasm.git"
+    },
+    "keywords": [
+        "sql",
+        "duckdb",
+        "relational",
+        "database",
+        "data",
+        "query",
+        "wasm",
+        "analytics",
+        "olap",
+        "arrow",
+        "parquet",
+        "json",
+        "csv"
+    ],
+    "files": [
+        "src"
+    ],
+    "main": "src/index.ts",
+    "types": "src/index.ts"
+}

package/src/connection_provider.tsx

@@ -0,0 +1,75 @@
+import React from 'react';
+import * as imm from 'immutable';
+import * as duckdb from '@duckdb/duckdb-wasm';
+import { useDuckDB } from './database_provider';
+import { useDuckDBLauncher } from './platform_provider';
+
+type DialerFn = (id?: number) => void;
+
+export const poolCtx = React.createContext<imm.Map<number, duckdb.AsyncDuckDBConnection>>(imm.Map());
+export const dialerCtx = React.createContext<DialerFn | null>(null);
+
+export const useDuckDBConnection = (id?: number): duckdb.AsyncDuckDBConnection | null =>
+    React.useContext(poolCtx)?.get(id || 0) || null;
+export const useDuckDBConnectionDialer = (): DialerFn => React.useContext(dialerCtx)!;
+
+type DuckDBConnectionProps = {
+    /// The children
+    children: React.ReactElement | React.ReactElement[];
+    /// The epoch
+    epoch?: number;
+};
+
+export const DuckDBConnectionProvider: React.FC<DuckDBConnectionProps> = (props: DuckDBConnectionProps) => {
+    const db = useDuckDB();
+    const launchDB = useDuckDBLauncher();
+    const launched = React.useRef<boolean>();
+    const [pending, setPending] = React.useState<imm.List<number>>(imm.List());
+    const [pool, setPool] = React.useState<imm.Map<number, duckdb.AsyncDuckDBConnection>>(imm.Map());
+
+    const inFlight = React.useRef<Map<number, boolean>>(new Map());
+
+    // Resolve request assuming that the database is ready
+    const dialer = async (id: number) => {
+        if (inFlight.current.get(id)) {
+            return;
+        }
+        const conn = await db!.connect();
+        setPool(p => p.set(id, conn));
+        inFlight.current.delete(id);
+    };
+
+    // Resolve request or remember as pending
+    const dialerCallback = React.useCallback(
+        (id?: number) => {
+            if (db != null) {
+                dialer(id || 0);
+            } else {
+                if (!launched.current) {
+                    launched.current = true;
+                    launchDB();
+                }
+                setPending(pending.push(id || 0));
+            }
+        },
+        [db],
+    );
+
+    // Process pending if possible
+    React.useEffect(() => {
+        if (!db) {
+            return;
+        }
+        const claimed = pending;
+        setPending(imm.List());
+        for (const id of claimed) {
+            dialer(id);
+        }
+    }, [db, pending]);
+
+    return (
+        <dialerCtx.Provider value={dialerCallback}>
+            <poolCtx.Provider value={pool}>{props.children}</poolCtx.Provider>
+        </dialerCtx.Provider>
+    );
+};

package/src/database_provider.tsx

@@ -0,0 +1,90 @@
+import React, { ReactElement } from 'react';
+import * as duckdb from '@duckdb/duckdb-wasm';
+import { useDuckDBLogger, useDuckDBBundle } from './platform_provider';
+
+export interface DuckDBStatus {
+    instantiationProgress: duckdb.InstantiationProgress | null;
+    instantiationError: any | null;
+}
+
+const dbCtx = React.createContext<duckdb.AsyncDuckDB | null>(null);
+const statusCtx = React.createContext<DuckDBStatus | null>(null);
+
+export const useDuckDB = (): duckdb.AsyncDuckDB | null => React.useContext(dbCtx);
+export const useDuckDBStatus = (): DuckDBStatus | null => React.useContext(statusCtx);
+
+type DuckDBProps = {
+    children: React.ReactElement | ReactElement[];
+    config?: duckdb.DuckDBConfig;
+};
+
+export const DuckDBProvider: React.FC<DuckDBProps> = (props: DuckDBProps) => {
+    const logger = useDuckDBLogger();
+    const bundle = useDuckDBBundle();
+    const [db, setDb] = React.useState<duckdb.AsyncDuckDB | null>(null);
+    const [status, setStatus] = React.useState<DuckDBStatus | null>(null);
+
+    // Reinitialize the worker and the database when the bundle changes
+    const lock = React.useRef<boolean>(false);
+    React.useEffect(() => {
+        // No bundle available?
+        if (!bundle) return;
+        // Is updating?
+        if (lock.current) return;
+        lock.current = true;
+
+        // Create worker and next database
+        let worker: Worker;
+        let next: duckdb.AsyncDuckDB;
+        try {
+            worker = new Worker(bundle.mainWorker!);
+            next = new duckdb.AsyncDuckDB(logger, worker);
+        } catch (e) {
+            lock.current = false;
+            setStatus({
+                instantiationProgress: null,
+                instantiationError: e,
+            });
+            return;
+        }
+
+        // Instantiate the database asynchronously
+        const init = async () => {
+            try {
+                await next.instantiate(bundle.mainModule, bundle.pthreadWorker, (p: duckdb.InstantiationProgress) => {
+                    try {
+                        setStatus({
+                            instantiationProgress: p,
+                            instantiationError: null,
+                        });
+                    } catch (e: any) {
+                        console.warn(`progress handler failed with error: ${e.toString()}`);
+                    }
+                });
+                if (props.config !== undefined) {
+                    await next.open(props.config!);
+                }
+            } catch (e) {
+                lock.current = false;
+                setStatus({
+                    instantiationProgress: null,
+                    instantiationError: e,
+                });
+                return;
+            }
+            lock.current = false;
+            setDb(next);
+        };
+        init();
+        // Terminate the worker on destruction
+        return () => {
+            worker.terminate();
+        };
+    }, [logger, bundle]);
+
+    return (
+        <dbCtx.Provider value={db}>
+            <statusCtx.Provider value={status}>{props.children}</statusCtx.Provider>
+        </dbCtx.Provider>
+    );
+};

package/src/epoch_contexts.tsx

@@ -0,0 +1,7 @@
+import React from 'react';
+
+export const TABLE_SCHEMA_EPOCH = React.createContext<number | null>(null);
+export const useTableSchemaEpoch = (): number | null => React.useContext(TABLE_SCHEMA_EPOCH);
+
+export const TABLE_DATA_EPOCH = React.createContext<number | null>(null);
+export const useTableDataEpoch = (): number | null => React.useContext(TABLE_DATA_EPOCH);

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './connection_provider';
+export * from './database_provider';
+export * from './platform_provider';
+export * from './table_schema';
+export * from './table_schema_provider';
+export * from './epoch_contexts';

package/src/platform_provider.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import * as duckdb from '@duckdb/duckdb-wasm';
+
+type PlatformProps = {
+    children: React.ReactElement | React.ReactElement[];
+    logger: duckdb.Logger;
+    bundles: duckdb.DuckDBBundles;
+};
+
+const loggerCtx = React.createContext<duckdb.Logger | null>(null);
+const bundleCtx = React.createContext<duckdb.DuckDBBundle | null>(null);
+const launcherCtx = React.createContext<(() => void) | null>(null);
+export const useDuckDBLauncher = (): (() => void) => React.useContext(launcherCtx)!;
+export const useDuckDBLogger = (): duckdb.Logger => React.useContext(loggerCtx)!;
+export const useDuckDBBundle = (): duckdb.DuckDBBundle => React.useContext(bundleCtx)!;
+
+export const DuckDBPlatform: React.FC<PlatformProps> = (props: PlatformProps) => {
+    const [bundle, setBundle] = React.useState<duckdb.DuckDBBundle | null>(null);
+    const [launched, setLaunched] = React.useState<boolean>(false);
+    const lock = React.useRef<boolean>(false);
+    React.useEffect(() => {
+        if (!launched || bundle != null || lock.current) return;
+        lock.current = true;
+        (async () => {
+            try {
+                const b = await duckdb.selectBundle(props.bundles);
+                setBundle(b);
+            } catch (e) {
+                console.error(e);
+            }
+            lock.current = false;
+        })();
+    }, [launched, props.bundles]);
+    const launcher = React.useCallback(() => setLaunched(true), [setLaunched]);
+    return (
+        <loggerCtx.Provider value={props.logger}>
+            <launcherCtx.Provider value={launcher}>
+                <bundleCtx.Provider value={bundle}>{props.children}</bundleCtx.Provider>
+            </launcherCtx.Provider>
+        </loggerCtx.Provider>
+    );
+};

package/src/table_schema.ts

@@ -0,0 +1,117 @@
+import * as arrow from 'apache-arrow';
+import * as duckdb from '@duckdb/duckdb-wasm';
+
+/// A column group
+export interface TableSchemaColumnGroup {
+    /// The group title
+    title: string;
+    /// The begin of the column span
+    spanBegin: number;
+    /// The size of the column span
+    spanSize: number;
+}
+
+/// A table metadatStorea
+export interface TableSchema {
+    /// The table schema
+    readonly tableSchema: string;
+    /// The table name
+    readonly tableName: string;
+
+    /// The column names
+    readonly columnNames: string[];
+    /// The column name indices
+    readonly columnNameMapping: Map<string, number>;
+    /// The column types
+    readonly columnTypes: arrow.DataType[];
+    /// The number of data columns.
+    /// Allows to append compute metadata columns that are not rendered in the table viewer.
+    readonly dataColumns: number;
+
+    /// The column aliases (if any)
+    readonly columnAliases: (string | null)[];
+    /// The column grouping sets (if any)
+    readonly columnGroupingSets: TableSchemaColumnGroup[][];
+    /// The row grouping sets (if any)
+    readonly rowGroupingSets: number[][];
+}
+
+/// Get raw qualified name
+export function getQualifiedNameRaw(schema: string, name: string) {
+    return `${schema || 'main'}.${name}`;
+}
+/// Get qualified name
+export function getQualifiedName(table: TableSchema) {
+    return `${table.tableSchema}.${table.tableName}`;
+}
+
+/// Collect table info
+export async function collectTableSchema(
+    conn: duckdb.AsyncDuckDBConnection,
+    info: Partial<TableSchema> & { tableSchema?: string; tableName: string },
+): Promise<TableSchema> {
+    // Use DESCRIBE to find all column types
+    const columnNames: string[] = [];
+    const columnNameMapping: Map<string, number> = new Map();
+    const columnTypes: arrow.DataType[] = [];
+    const describe = await conn.query<{ Field: arrow.Utf8; Type: arrow.Utf8 }>(
+        `DESCRIBE ${info.tableSchema || 'main'}.${info.tableName}`,
+    );
+    let column = 0;
+    for (const row of describe) {
+        columnNames.push(row!.Field!);
+        columnNameMapping.set(row!.Field!, column++);
+        const mapType = (type: string): arrow.DataType => {
+            switch (type) {
+                case 'BOOLEAN':
+                    return new arrow.Bool();
+                case 'TINYINT':
+                    return new arrow.Int8();
+                case 'SMALLINT':
+                    return new arrow.Int16();
+                case 'INTEGER':
+                    return new arrow.Int32();
+                case 'BIGINT':
+                    return new arrow.Int64();
+                case 'UTINYINT':
+                    return new arrow.Uint8();
+                case 'USMALLINT':
+                    return new arrow.Uint16();
+                case 'UINTEGER':
+                    return new arrow.Uint32();
+                case 'UBIGINT':
+                    return new arrow.Uint64();
+                case 'FLOAT':
+                    return new arrow.Float32();
+                case 'HUGEINT':
+                    return new arrow.Decimal(32, 0);
+                case 'DOUBLE':
+                    return new arrow.Float64();
+                case 'VARCHAR':
+                    return new arrow.Utf8();
+                case 'DATE':
+                    return new arrow.DateDay();
+                case 'TIME':
+                    return new arrow.Time(arrow.TimeUnit.MILLISECOND, 32);
+                case 'TIMESTAMP':
+                    return new arrow.TimeNanosecond();
+                default:
+                    return new arrow.Null();
+            }
+        };
+        columnTypes.push(mapType(row!.Type!));
+    }
+    const table: TableSchema = {
+        ...info,
+        tableSchema: info.tableSchema || 'main',
+        columnNames,
+        columnTypes,
+        dataColumns: columnTypes.length,
+        columnNameMapping,
+        columnAliases: [],
+        columnGroupingSets: [],
+        rowGroupingSets: [],
+    };
+
+    return table;
+}

package/src/table_schema_provider.tsx

@@ -0,0 +1,70 @@
+import * as React from 'react';
+import { TableSchema, collectTableSchema } from './table_schema';
+import { useTableSchemaEpoch } from './epoch_contexts';
+import { useDuckDBConnection } from './connection_provider';
+
+interface Props {
+    /// The children
+    children: React.ReactElement | React.ReactElement[];
+    /// The schema
+    schema?: string;
+    /// The name
+    name: string;
+}
+
+interface State {
+    /// The schema
+    schema: string | null;
+    /// The name
+    name: string | null;
+    /// The metadata
+    metadata: TableSchema | null;
+    /// The own epoch
+    ownEpoch: number | null;
+}
+
+export const TABLE_METADATA = React.createContext<TableSchema | null>(null);
+export const useTableSchema = (): TableSchema | null => React.useContext(TABLE_METADATA);
+
+export const DuckDBTableSchemaProvider: React.FC<Props> = (props: Props) => {
+    const conn = useDuckDBConnection();
+    const epoch = useTableSchemaEpoch();
+    const [state, setState] = React.useState<State>({
+        schema: null,
+        name: null,
+        ownEpoch: epoch,
+        metadata: null,
+    });
+    const inFlight = React.useRef<boolean>(false);
+
+    // Detect unmount
+    const isMounted = React.useRef(true);
+    React.useEffect(() => {
+        return () => void (isMounted.current = false);
+    }, []);
+
+    // Resolve the metadata
+    React.useEffect(() => {
+        if (!isMounted.current || !conn || inFlight.current) {
+            return;
+        }
+        inFlight.current = true;
+        const resolve = async (schema: string, name: string, epoch: number | null) => {
+            const metadata = await collectTableSchema(conn!, {
+                tableSchema: schema,
+                tableName: name,
+            });
+            inFlight.current = false;
+            if (!isMounted.current) return;
+            setState({
+                schema,
+                name,
+                ownEpoch: epoch,
+                metadata,
+            });
+        };
+        resolve(props.schema || 'main', props.name, epoch).catch(e => console.error(e));
+    }, [conn, props.schema, props.name, epoch]);
+
+    return <TABLE_METADATA.Provider value={state.metadata}>{props.children}</TABLE_METADATA.Provider>;
+};