@sqlrooms/duckdb 0.5.1 → 0.7.0

package/README.md

@@ -0,0 +1,169 @@
+A powerful wrapper around DuckDB-WASM that provides React hooks and utilities for working with DuckDB in browser environments.
+
+## Features
+
+- 🔄 **React Integration**: Hooks for seamless integration with React applications
+- 📊 **Type-Safe Queries**: Execute SQL queries with TypeScript type safety
+- 🔍 **Data Validation**: Optional runtime validation using Zod schemas
+- 📁 **File Operations**: Import data from various file formats (CSV, JSON, Parquet)
+- 📤 **Data Export**: Export query results to CSV files
+- 🏹 **Arrow Integration**: Work with Apache Arrow tables for efficient data processing
+
+## Installation
+
+```bash
+npm install @sqlrooms/duckdb
+```
+
+## Basic Usage
+
+### Using the SQL Hook
+
+````tsx
+import {useSql} from '@sqlrooms/duckdb';
+
+function UserList() {
+  // Basic usage with TypeScript types
+  const {data, isLoading, error} = useSql<{id: number; name: string}>({
+    query: 'SELECT id, name FROM users',
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!data) return null;
+
+  return (
+    <ul>
+      {Array.from(data.rows()).map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+For more information and examples on using the `useSql` hook, see the [useSql API documentation](/api/duckdb/functions/useSql).
+
+### Using Zod for Runtime Validation
+
+```tsx
+import {useSql} from '@sqlrooms/duckdb';
+import {z} from 'zod';
+
+const userSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+  created_at: z.string().transform((str) => new Date(str)),
+});
+
+function ValidatedUserList() {
+  const {data, isLoading, error} = useSql(userSchema, {
+    query: 'SELECT id, name, email, created_at FROM users',
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) {
+    if (error instanceof z.ZodError) {
+      return <div>Validation Error: {error.errors[0].message}</div>;
+    }
+    return <div>Error: {error.message}</div>;
+  }
+  if (!data) return null;
+
+  return (
+    <ul>
+      {data.toArray().map((user) => (
+        <li key={user.id}>
+          {user.name} ({user.email}) - Joined:{' '}
+          {user.created_at.toLocaleDateString()}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Creating Tables from Different Sources
+
+```tsx
+import {
+  createTableFromQuery,
+  createTableFromObjects,
+  createViewFromFile,
+} from '@sqlrooms/duckdb';
+
+// Create a table from a SQL query
+await createTableFromQuery(
+  'filtered_users',
+  'SELECT * FROM users WHERE active = true',
+);
+
+// Create a table from JavaScript objects
+const users = [
+  {id: 1, name: 'Alice', email: 'alice@example.com'},
+  {id: 2, name: 'Bob', email: 'bob@example.com'},
+];
+await createTableFromObjects('new_users', users);
+
+// Create a view from a file upload
+function FileUploader() {
+  const handleFileUpload = async (event) => {
+    const file = event.target.files[0];
+    if (file) {
+      await createViewFromFile(file.name, 'main', 'uploaded_data', file);
+    }
+  };
+
+  return (
+    <input
+      type="file"
+      accept=".csv,.json,.parquet"
+      onChange={handleFileUpload}
+    />
+  );
+}
+```
+
+### Exporting Data to CSV
+
+```tsx
+import {exportToCsv} from '@sqlrooms/duckdb';
+
+function ExportButton() {
+  const handleExport = async () => {
+    await exportToCsv('SELECT * FROM users ORDER BY name', 'users_export.csv');
+  };
+
+  return <button onClick={handleExport}>Export to CSV</button>;
+}
+```
+
+### Low-Level DuckDB Access
+
+```tsx
+import {getDuckDb} from '@sqlrooms/duckdb';
+
+async function executeCustomQuery() {
+  const {conn} = await getDuckDb();
+
+  // Execute a query directly
+  const result = await conn.query('SELECT COUNT(*) as count FROM users');
+
+  // Access the Arrow table directly
+  const count = result.getChildAt(0)?.get(0);
+  console.log(`Total users: ${count}`);
+
+  return result;
+}
+```
+
+## Advanced Features
+
+- **Batch Processing**: Handle large datasets with pagination
+- **Arrow Integration**: Work directly with Apache Arrow tables for efficient data processing
+- **Schema Management**: Create, inspect, and manage database schemas
+- **File Management**: Register and manage files in the DuckDB instance
+
+For more information, visit the SQLRooms documentation.
+````

package/dist/index.d.ts

@@ -1,7 +1,11 @@
+/**
+ * {@include ../README.md}
+ * @packageDocumentation
+ */
 export * from './duckdb';
 export * from './types';
 export * from './useDuckDb';
 export * from './exportToCsv';
 export * from './arrow-utils';
-export * from './useDuckDbQuery';
+export * from './useSql';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -1,7 +1,11 @@
+/**
+ * {@include ../README.md}
+ * @packageDocumentation
+ */
 export * from './duckdb';
 export * from './types';
 export * from './useDuckDb';
 export * from './exportToCsv';
 export * from './arrow-utils';
-export * from './useDuckDbQuery';
+export * from './useSql';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC","sourcesContent":["export * from './duckdb';\nexport * from './types';\nexport * from './useDuckDb';\nexport * from './exportToCsv';\nexport * from './arrow-utils';\nexport * from './useDuckDbQuery';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC","sourcesContent":["/**\n * {@include ../README.md}\n * @packageDocumentation\n */\n\nexport * from './duckdb';\nexport * from './types';\nexport * from './useDuckDb';\nexport * from './exportToCsv';\nexport * from './arrow-utils';\nexport * from './useSql';\n"]}

package/dist/useSql.d.ts

@@ -0,0 +1,184 @@
+import * as arrow from 'apache-arrow';
+import { z } from 'zod';
+/**
+ * A wrapper interface that exposes the underlying Arrow table,
+ * a typed row accessor, and the number of rows.
+ */
+export interface UseSqlQueryResult<T> {
+    /** The underlying Arrow table */
+    arrowTable: arrow.Table;
+    /** Returns a typed row at the specified index by converting on demand */
+    getRow(index: number): T;
+    /** Number of rows in the table */
+    length: number;
+    /** Returns an iterator that yields each row in the table */
+    rows(): IterableIterator<T>;
+    /** Returns an array containing all rows in the table */
+    toArray(): T[];
+}
+/**
+ * @deprecated Use UseSqlQueryResult instead
+ */
+export type DuckDbQueryResult<T> = UseSqlQueryResult<T>;
+/**
+ * A React hook for executing SQL queries with automatic state management.
+ * Provides two ways to ensure type safety:
+ * 1. Using TypeScript types (compile-time safety only)
+ * 2. Using Zod schemas (both compile-time and runtime validation)
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Using TypeScript types (faster, no runtime validation)
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const {data, isLoading, error} = useSql<User>({
+ *   query: 'SELECT id, name, email FROM users'
+ * });
+ *
+ * // Option 2: Using Zod schema (slower but with runtime validation)
+ * const userSchema = z.object({
+ *   id: z.number(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ *   createdAt: z.string().transform(str => new Date(str)) // Transform string to Date
+ * });
+ *
+ * const {data: validatedData, isLoading, error} = useSql(
+ *   userSchema,
+ *   {query: 'SELECT id, name, email, created_at as createdAt FROM users'}
+ * );
+ * ```
+ *
+ * ## Error Handling
+ * ```typescript
+ * if (isLoading) return <div>Loading...</div>;
+ * if (error) {
+ *   // With Zod, you can catch validation errors specifically
+ *   if (error instanceof z.ZodError) {
+ *     return <div>Validation Error: {error.errors[0].message}</div>;
+ *   }
+ *   return <div>Error: {error.message}</div>;
+ * }
+ * if (!data) return null;
+ * ```
+ *
+ * ## Data Access Methods
+ *
+ * There are several ways to access data with different performance characteristics:
+ *
+ * ### 1. Typed Row Access (getRow, rows(), toArray())
+ * - Provides type safety and validation
+ * - Converts data to JavaScript objects
+ * - Slower for large datasets due to object creation and validation
+ *
+ * ```typescript
+ * // Iterate through rows using the rows() iterator (recommended)
+ * for (const user of data.rows()) {
+ *   console.log(user.name, user.email);
+ * }
+ *
+ * // Traditional for loop with index access
+ * for (let i = 0; i < data.length; i++) {
+ *   const user = data.getRow(i);
+ *   console.log(`User ${i}: ${user.name} (${user.email})`);
+ * }
+ *
+ * // Get all rows as an array
+ * const allUsers = data.toArray();
+ *
+ * // With Zod schema, transformed fields are available
+ * for (const user of validatedData.rows()) {
+ *   console.log(`Created: ${user.createdAt.toISOString()}`); // createdAt is a Date object
+ * }
+ * ```
+ *
+ * ### 2. Direct Arrow Table Access
+ * - Much faster for large datasets
+ * - Columnar access is more efficient for analytics
+ * - No type safety or validation
+ *
+ * ```typescript
+ * // For performance-critical operations with large datasets:
+ * const nameColumn = data.arrowTable.getChild('name');
+ * const emailColumn = data.arrowTable.getChild('email');
+ *
+ * // Fast columnar iteration (no object creation)
+ * for (let i = 0; i < data.length; i++) {
+ *   console.log(nameColumn.get(i), emailColumn.get(i));
+ * }
+ *
+ * // Note: For filtering data, it's most efficient to use SQL in your query
+ * const { data } = useSql<User>({
+ *   query: "SELECT * FROM users WHERE age > 30"
+ * });
+ * ```
+ *
+ * ### 3. Using Flechette for Advanced Operations
+ *
+ * For more advanced Arrow operations, consider using [Flechette](https://idl.uw.edu/flechette/),
+ * a faster and lighter alternative to the standard Arrow JS implementation.
+ *
+ * ```typescript
+ * // Example using Flechette with SQL query results
+ * import { tableFromIPC } from '@uwdata/flechette';
+ *
+ * // Convert Arrow table to Flechette table
+ * const serializedData = data.arrowTable.serialize();
+ * const flechetteTable = tableFromIPC(serializedData);
+ *
+ * // Extract all columns into a { name: array, ... } object
+ * const columns = flechetteTable.toColumns();
+ *
+ * // Create a new table with a selected subset of columns
+ * const subtable = flechetteTable.select(['name', 'email']);
+ *
+ * // Convert to array of objects with customization options
+ * const objects = flechetteTable.toArray({
+ *   useDate: true,  // Convert timestamps to Date objects
+ *   useMap: true    // Create Map objects for key-value pairs
+ * });
+ *
+ * // For large datasets, consider memory management
+ * serializedData = null; // Allow garbage collection of the serialized data
+ * ```
+ *
+ * Flechette provides several advantages:
+ * - Better performance (1.3-1.6x faster value iteration, 7-11x faster row object extraction)
+ * - Smaller footprint (~43k minified vs 163k for Arrow JS)
+ * - Support for additional data types (including decimal-to-number conversion)
+ * - More flexible data value conversion options
+ *
+ * @template Row The TypeScript type for each row in the result
+ * @param options Configuration object containing the query and execution control
+ * @returns Object containing the query result, loading state, and any error
+ *
+ * @template Schema The Zod schema type that defines the shape and validation of each row
+ * @param schema A Zod schema that defines the expected shape and validation rules for each row
+ * @param options Configuration object containing the query and execution control
+ * @returns Object containing the validated query result, loading state, and any error
+ */
+export declare function useSql<Row>(options: {
+    query: string;
+    enabled?: boolean;
+}): {
+    data: UseSqlQueryResult<Row> | undefined;
+    error: Error | null;
+    isLoading: boolean;
+};
+export declare function useSql<Schema extends z.ZodType>(schema: Schema, options: {
+    query: string;
+    enabled?: boolean;
+}): {
+    data: UseSqlQueryResult<z.infer<Schema>> | undefined;
+    error: Error | null;
+    isLoading: boolean;
+};
+/**
+ * @deprecated Use useSql instead
+ */
+export declare const useDuckDbQuery: typeof useSql;
+//# sourceMappingURL=useSql.d.ts.map

package/dist/useSql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSql.d.ts","sourceRoot":"","sources":["../src/useSql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,iCAAiC;IACjC,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC;IACxB,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC;IACzB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC5B,wDAAwD;IACxD,OAAO,IAAI,CAAC,EAAE,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC;AA+CxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4IG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAC,GAAG;IACxE,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IACzC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,wBAAgB,MAAM,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EAC7C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA;IACD,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IACrD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAuEF;;GAEG;AACH,eAAO,MAAM,cAAc,eAAS,CAAC"}

package/dist/{useDuckDbQuery.js → useSql.js}

@@ -23,12 +23,24 @@ function createTypedRowAccessor({ arrowTable, validate, }) {
             }
             return row;
         },
+        *rows() {
+            for (let i = 0; i < this.length; i++) {
+                yield this.getRow(i);
+            }
+        },
+        toArray() {
+            const result = [];
+            for (let i = 0; i < this.length; i++) {
+                result.push(this.getRow(i));
+            }
+            return result;
+        },
     };
 }
 /**
- * Implementation of useDuckDbQuery that handles both overloads
+ * Implementation of useSql that handles both overloads
  */
-export function useDuckDbQuery(schemaOrOptions, maybeOptions) {
+export function useSql(schemaOrOptions, maybeOptions) {
     // Determine if we're using the schema overload
     const hasSchema = maybeOptions !== undefined;
     const options = hasSchema
@@ -80,4 +92,8 @@ export function useDuckDbQuery(schemaOrOptions, maybeOptions) {
         isLoading,
     };
 }
-//# sourceMappingURL=useDuckDbQuery.js.map
+/**
+ * @deprecated Use useSql instead
+ */
+export const useDuckDbQuery = useSql;
+//# sourceMappingURL=useSql.js.map

package/dist/useSql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSql.js","sourceRoot":"","sources":["../src/useSql.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAyBtC;;GAEG;AACH,SAAS,sBAAsB,CAAI,EACjC,UAAU,EACV,QAAQ,GAIT;IACC,OAAO;QACL,UAAU;QACV,IAAI,MAAM;YACR,OAAO,UAAU,CAAC,OAAO,CAAC;QAC5B,CAAC;QACD,MAAM,CAAC,KAAa;YAClB,MAAM,GAAG,GAA4B,EAAE,CAAC;YACxC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAkB,EAAE,EAAE;gBACtD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC/C,IAAI,MAAM,EAAE,CAAC;oBACX,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACtC,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,+DAA+D;YAC/D,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;YACD,OAAO,GAAQ,CAAC;QAClB,CAAC;QACD,CAAC,IAAI;YACH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QACD,OAAO;YACL,MAAM,MAAM,GAAQ,EAAE,CAAC;YACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9B,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAiKD;;GAEG;AACH,MAAM,UAAU,MAAM,CACpB,eAA4D,EAC5D,YAAiD;IAEjD,+CAA+C;IAC/C,MAAM,SAAS,GAAG,YAAY,KAAK,SAAS,CAAC;IAC7C,MAAM,OAAO,GAAG,SAAS;QACvB,CAAC,CAAC,YAAY;QACd,CAAC,CAAE,eAAsD,CAAC;IAC5D,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAE,eAA0B,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAC9B,SAAS,CACV,CAAC;IACF,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IACvD,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAElD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,SAAS,GAAG,IAAI,CAAC;QAErB,MAAM,SAAS,GAAG,KAAK,IAAI,EAAE;YAC3B,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBACtD,OAAO;YACT,CAAC;YAED,YAAY,CAAC,IAAI,CAAC,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;YAEf,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;gBACjC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAEtD,kEAAkE;gBAClE,MAAM,WAAW,GAAG,sBAAsB,CAAM;oBAC9C,UAAU,EAAE,MAAM;oBAClB,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;iBACnE,CAAC,CAAC;gBAEH,IAAI,SAAS,EAAE,CAAC;oBACd,OAAO,CAAC,WAAW,CAAC,CAAC;gBACvB,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,SAAS,EAAE,CAAC;oBACd,QAAQ,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBAChE,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,IAAI,SAAS,EAAE,CAAC;oBACd,YAAY,CAAC,KAAK,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC,CAAC;QAEF,SAAS,EAAE,CAAC;QAEZ,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAErC,OAAO;QACL,IAAI;QACJ,KAAK;QACL,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC","sourcesContent":["import * as arrow from 'apache-arrow';\nimport {useEffect, useState} from 'react';\nimport {getDuckDb} from './useDuckDb';\nimport {z} from 'zod';\n\n/**\n * A wrapper interface that exposes the underlying Arrow table,\n * a typed row accessor, and the number of rows.\n */\nexport interface UseSqlQueryResult<T> {\n  /** The underlying Arrow table */\n  arrowTable: arrow.Table;\n  /** Returns a typed row at the specified index by converting on demand */\n  getRow(index: number): T;\n  /** Number of rows in the table */\n  length: number;\n  /** Returns an iterator that yields each row in the table */\n  rows(): IterableIterator<T>;\n  /** Returns an array containing all rows in the table */\n  toArray(): T[];\n}\n\n/**\n * @deprecated Use UseSqlQueryResult instead\n */\nexport type DuckDbQueryResult<T> = UseSqlQueryResult<T>;\n\n/**\n * Creates a row accessor wrapper around an Arrow table that provides typed row access.\n */\nfunction createTypedRowAccessor<T>({\n  arrowTable,\n  validate,\n}: {\n  arrowTable: arrow.Table;\n  validate?: (row: unknown) => T;\n}): UseSqlQueryResult<T> {\n  return {\n    arrowTable,\n    get length() {\n      return arrowTable.numRows;\n    },\n    getRow(index: number): T {\n      const row: Record<string, unknown> = {};\n      arrowTable.schema.fields.forEach((field: arrow.Field) => {\n        const column = arrowTable.getChild(field.name);\n        if (column) {\n          row[field.name] = column.get(index);\n        }\n      });\n\n      // If a validator is provided, use it to validate/parse the row\n      if (validate) {\n        return validate(row);\n      }\n      return row as T;\n    },\n    *rows(): IterableIterator<T> {\n      for (let i = 0; i < this.length; i++) {\n        yield this.getRow(i);\n      }\n    },\n    toArray(): T[] {\n      const result: T[] = [];\n      for (let i = 0; i < this.length; i++) {\n        result.push(this.getRow(i));\n      }\n      return result;\n    },\n  };\n}\n\n/**\n * A React hook for executing SQL queries with automatic state management.\n * Provides two ways to ensure type safety:\n * 1. Using TypeScript types (compile-time safety only)\n * 2. Using Zod schemas (both compile-time and runtime validation)\n *\n * @example\n * ```typescript\n * // Option 1: Using TypeScript types (faster, no runtime validation)\n * interface User {\n *   id: number;\n *   name: string;\n *   email: string;\n * }\n *\n * const {data, isLoading, error} = useSql<User>({\n *   query: 'SELECT id, name, email FROM users'\n * });\n *\n * // Option 2: Using Zod schema (slower but with runtime validation)\n * const userSchema = z.object({\n *   id: z.number(),\n *   name: z.string(),\n *   email: z.string().email(),\n *   createdAt: z.string().transform(str => new Date(str)) // Transform string to Date\n * });\n *\n * const {data: validatedData, isLoading, error} = useSql(\n *   userSchema,\n *   {query: 'SELECT id, name, email, created_at as createdAt FROM users'}\n * );\n * ```\n *\n * ## Error Handling\n * ```typescript\n * if (isLoading) return <div>Loading...</div>;\n * if (error) {\n *   // With Zod, you can catch validation errors specifically\n *   if (error instanceof z.ZodError) {\n *     return <div>Validation Error: {error.errors[0].message}</div>;\n *   }\n *   return <div>Error: {error.message}</div>;\n * }\n * if (!data) return null;\n * ```\n *\n * ## Data Access Methods\n *\n * There are several ways to access data with different performance characteristics:\n *\n * ### 1. Typed Row Access (getRow, rows(), toArray())\n * - Provides type safety and validation\n * - Converts data to JavaScript objects\n * - Slower for large datasets due to object creation and validation\n *\n * ```typescript\n * // Iterate through rows using the rows() iterator (recommended)\n * for (const user of data.rows()) {\n *   console.log(user.name, user.email);\n * }\n *\n * // Traditional for loop with index access\n * for (let i = 0; i < data.length; i++) {\n *   const user = data.getRow(i);\n *   console.log(`User ${i}: ${user.name} (${user.email})`);\n * }\n *\n * // Get all rows as an array\n * const allUsers = data.toArray();\n *\n * // With Zod schema, transformed fields are available\n * for (const user of validatedData.rows()) {\n *   console.log(`Created: ${user.createdAt.toISOString()}`); // createdAt is a Date object\n * }\n * ```\n *\n * ### 2. Direct Arrow Table Access\n * - Much faster for large datasets\n * - Columnar access is more efficient for analytics\n * - No type safety or validation\n *\n * ```typescript\n * // For performance-critical operations with large datasets:\n * const nameColumn = data.arrowTable.getChild('name');\n * const emailColumn = data.arrowTable.getChild('email');\n *\n * // Fast columnar iteration (no object creation)\n * for (let i = 0; i < data.length; i++) {\n *   console.log(nameColumn.get(i), emailColumn.get(i));\n * }\n *\n * // Note: For filtering data, it's most efficient to use SQL in your query\n * const { data } = useSql<User>({\n *   query: \"SELECT * FROM users WHERE age > 30\"\n * });\n * ```\n *\n * ### 3. Using Flechette for Advanced Operations\n *\n * For more advanced Arrow operations, consider using [Flechette](https://idl.uw.edu/flechette/),\n * a faster and lighter alternative to the standard Arrow JS implementation.\n *\n * ```typescript\n * // Example using Flechette with SQL query results\n * import { tableFromIPC } from '@uwdata/flechette';\n *\n * // Convert Arrow table to Flechette table\n * const serializedData = data.arrowTable.serialize();\n * const flechetteTable = tableFromIPC(serializedData);\n *\n * // Extract all columns into a { name: array, ... } object\n * const columns = flechetteTable.toColumns();\n *\n * // Create a new table with a selected subset of columns\n * const subtable = flechetteTable.select(['name', 'email']);\n *\n * // Convert to array of objects with customization options\n * const objects = flechetteTable.toArray({\n *   useDate: true,  // Convert timestamps to Date objects\n *   useMap: true    // Create Map objects for key-value pairs\n * });\n *\n * // For large datasets, consider memory management\n * serializedData = null; // Allow garbage collection of the serialized data\n * ```\n *\n * Flechette provides several advantages:\n * - Better performance (1.3-1.6x faster value iteration, 7-11x faster row object extraction)\n * - Smaller footprint (~43k minified vs 163k for Arrow JS)\n * - Support for additional data types (including decimal-to-number conversion)\n * - More flexible data value conversion options\n *\n * @template Row The TypeScript type for each row in the result\n * @param options Configuration object containing the query and execution control\n * @returns Object containing the query result, loading state, and any error\n *\n * @template Schema The Zod schema type that defines the shape and validation of each row\n * @param schema A Zod schema that defines the expected shape and validation rules for each row\n * @param options Configuration object containing the query and execution control\n * @returns Object containing the validated query result, loading state, and any error\n */\nexport function useSql<Row>(options: {query: string; enabled?: boolean}): {\n  data: UseSqlQueryResult<Row> | undefined;\n  error: Error | null;\n  isLoading: boolean;\n};\n\nexport function useSql<Schema extends z.ZodType>(\n  schema: Schema,\n  options: {\n    query: string;\n    enabled?: boolean;\n  },\n): {\n  data: UseSqlQueryResult<z.infer<Schema>> | undefined;\n  error: Error | null;\n  isLoading: boolean;\n};\n\n/**\n * Implementation of useSql that handles both overloads\n */\nexport function useSql<Row, Schema extends z.ZodType = z.ZodType>(\n  schemaOrOptions: Schema | {query: string; enabled?: boolean},\n  maybeOptions?: {query: string; enabled?: boolean},\n) {\n  // Determine if we're using the schema overload\n  const hasSchema = maybeOptions !== undefined;\n  const options = hasSchema\n    ? maybeOptions\n    : (schemaOrOptions as {query: string; enabled?: boolean});\n  const schema = hasSchema ? (schemaOrOptions as Schema) : undefined;\n\n  const [data, setData] = useState<UseSqlQueryResult<Row> | undefined>(\n    undefined,\n  );\n  const [error, setError] = useState<Error | null>(null);\n  const [isLoading, setIsLoading] = useState(false);\n\n  useEffect(() => {\n    let isMounted = true;\n\n    const fetchData = async () => {\n      if (!options.enabled && options.enabled !== undefined) {\n        return;\n      }\n\n      setIsLoading(true);\n      setError(null);\n\n      try {\n        const duckDb = await getDuckDb();\n        const result = await duckDb.conn.query(options.query);\n\n        // Create a row accessor that optionally validates with the schema\n        const rowAccessor = createTypedRowAccessor<Row>({\n          arrowTable: result,\n          validate: schema ? (row: unknown) => schema.parse(row) : undefined,\n        });\n\n        if (isMounted) {\n          setData(rowAccessor);\n        }\n      } catch (err) {\n        if (isMounted) {\n          setError(err instanceof Error ? err : new Error(String(err)));\n        }\n      } finally {\n        if (isMounted) {\n          setIsLoading(false);\n        }\n      }\n    };\n\n    fetchData();\n\n    return () => {\n      isMounted = false;\n    };\n  }, [options.query, options.enabled]);\n\n  return {\n    data,\n    error,\n    isLoading,\n  };\n}\n\n/**\n * @deprecated Use useSql instead\n */\nexport const useDuckDbQuery = useSql;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqlrooms/duckdb",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.js",
@@ -19,12 +19,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@duckdb/duckdb-wasm": "^1.29.1-dev68.0",
+    "@duckdb/duckdb-wasm": "1.29.0",
     "apache-arrow": "^18.1.0",
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@sqlrooms/jest-config": "0.5.1",
+    "@sqlrooms/jest-config": "0.7.0",
     "@types/jest": "^29.5.12",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.2"
@@ -38,5 +38,5 @@
     "test": "jest",
     "test:watch": "jest --watch"
   },
-  "gitHead": "5e41362f1552ee1f8a661c487fe7cdb606cc6d23"
+  "gitHead": "8be65f051c588d3a963f721322429657913b6c63"
 }

package/dist/useDuckDbQuery.d.ts

@@ -1,106 +0,0 @@
-import * as arrow from 'apache-arrow';
-import { z } from 'zod';
-/**
- * A wrapper interface that exposes the underlying Arrow table,
- * a typed row accessor, and the number of rows.
- */
-export interface DuckDbQueryResult<T> {
-    /** The underlying Arrow table */
-    arrowTable: arrow.Table;
-    /** Returns a typed row at the specified index by converting on demand */
-    getRow(index: number): T;
-    /** Number of rows in the table */
-    length: number;
-}
-/**
- * A React hook for executing DuckDB queries with automatic state management.
- * This version provides type safety through TypeScript types but no runtime validation.
- *
- * @example
- * ```typescript
- * interface User {
- *   id: number;
- *   name: string;
- *   email: string;
- * }
- *
- * const {data, isLoading, error} = useDuckDbQuery<User>({
- *   query: 'SELECT id, name, email FROM users'
- * });
- *
- * if (isLoading) return <div>Loading...</div>;
- * if (error) return <div>Error: {error.message}</div>;
- * if (!data) return null;
- *
- * // Access typed rows
- * const firstUser = data.getRow(0); // Type: User
- * console.log(firstUser.name);
- * ```
- *
- * @template Row The TypeScript type for each row in the result
- * @param options Configuration object containing the query and execution control
- * @returns Object containing the query result, loading state, and any error
- */
-export declare function useDuckDbQuery<Row>(options: {
-    query: string;
-    enabled?: boolean;
-}): {
-    data: DuckDbQueryResult<Row> | undefined;
-    error: Error | null;
-    isLoading: boolean;
-};
-/**
- * A React hook for executing DuckDB queries with automatic state management and runtime validation.
- * This version uses Zod schemas to provide both compile-time and runtime type safety.
- *
- * Key features:
- * - Runtime validation of each row as it's accessed
- * - Automatic TypeScript type inference from the Zod schema
- * - Validation errors if the data doesn't match the expected shape
- * - Ability to transform data during validation
- *
- * @example
- * ```typescript
- * // Define a schema for your data
- * const userSchema = z.object({
- *   id: z.number(),
- *   name: z.string(),
- *   email: z.string().email(),
- *   createdAt: z.string().transform(str => new Date(str)) // Transform string to Date
- * });
- *
- * // The type is automatically inferred from the schema
- * const {data, isLoading, error} = useDuckDbQuery(
- *   userSchema,
- *   {query: 'SELECT id, name, email, created_at FROM users'}
- * );
- *
- * if (isLoading) return <div>Loading...</div>;
- * if (error) {
- *   // Error will be a ZodError if validation fails
- *   if (error instanceof z.ZodError) {
- *     return <div>Validation Error: {error.errors[0].message}</div>;
- *   }
- *   return <div>Error: {error.message}</div>;
- * }
- * if (!data) return null;
- *
- * // Rows are validated and transformed according to the schema
- * const user = data.getRow(0);
- * console.log(user.createdAt.toISOString()); // createdAt is now a Date object
- * ```
- *
- * @template Schema The Zod schema type that defines the shape and validation of each row
- * @param schema A Zod schema that defines the expected shape and validation rules for each row
- * @param options Configuration object containing the query and execution control
- * @returns Object containing the validated query result, loading state, and any error
- */
-export declare function useDuckDbQuery<Schema extends z.ZodType>(schema: Schema, options: {
-    query: string;
-    enabled?: boolean;
-}): {
-    data: DuckDbQueryResult<z.infer<Schema>> | undefined;
-    error: Error | null;
-    isLoading: boolean;
-};
-//# sourceMappingURL=useDuckDbQuery.d.ts.map

package/dist/useDuckDbQuery.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useDuckDbQuery.d.ts","sourceRoot":"","sources":["../src/useDuckDbQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,iCAAiC;IACjC,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC;IACxB,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC;IACzB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG;IACF,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IACzC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,cAAc,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EACrD,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA;IACD,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IACrD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC"}

package/dist/useDuckDbQuery.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"useDuckDbQuery.js","sourceRoot":"","sources":["../src/useDuckDbQuery.ts"],"names":[],"mappings":"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","sourcesContent":["import * as arrow from 'apache-arrow';\nimport {useEffect, useState} from 'react';\nimport {getDuckDb} from './useDuckDb';\nimport {z} from 'zod';\n\n/**\n * A wrapper interface that exposes the underlying Arrow table,\n * a typed row accessor, and the number of rows.\n */\nexport interface DuckDbQueryResult<T> {\n  /** The underlying Arrow table */\n  arrowTable: arrow.Table;\n  /** Returns a typed row at the specified index by converting on demand */\n  getRow(index: number): T;\n  /** Number of rows in the table */\n  length: number;\n}\n\n/**\n * Creates a row accessor wrapper around an Arrow table that provides typed row access.\n */\nfunction createTypedRowAccessor<T>({\n  arrowTable,\n  validate,\n}: {\n  arrowTable: arrow.Table;\n  validate?: (row: unknown) => T;\n}): DuckDbQueryResult<T> {\n  return {\n    arrowTable,\n    get length() {\n      return arrowTable.numRows;\n    },\n    getRow(index: number): T {\n      const row: Record<string, unknown> = {};\n      arrowTable.schema.fields.forEach((field: arrow.Field) => {\n        const column = arrowTable.getChild(field.name);\n        if (column) {\n          row[field.name] = column.get(index);\n        }\n      });\n\n      // If a validator is provided, use it to validate/parse the row\n      if (validate) {\n        return validate(row);\n      }\n      return row as T;\n    },\n  };\n}\n\n/**\n * A React hook for executing DuckDB queries with automatic state management.\n * This version provides type safety through TypeScript types but no runtime validation.\n *\n * @example\n * ```typescript\n * interface User {\n *   id: number;\n *   name: string;\n *   email: string;\n * }\n *\n * const {data, isLoading, error} = useDuckDbQuery<User>({\n *   query: 'SELECT id, name, email FROM users'\n * });\n *\n * if (isLoading) return <div>Loading...</div>;\n * if (error) return <div>Error: {error.message}</div>;\n * if (!data) return null;\n *\n * // Access typed rows\n * const firstUser = data.getRow(0); // Type: User\n * console.log(firstUser.name);\n * ```\n *\n * @template Row The TypeScript type for each row in the result\n * @param options Configuration object containing the query and execution control\n * @returns Object containing the query result, loading state, and any error\n */\nexport function useDuckDbQuery<Row>(options: {\n  query: string;\n  enabled?: boolean;\n}): {\n  data: DuckDbQueryResult<Row> | undefined;\n  error: Error | null;\n  isLoading: boolean;\n};\n\n/**\n * A React hook for executing DuckDB queries with automatic state management and runtime validation.\n * This version uses Zod schemas to provide both compile-time and runtime type safety.\n *\n * Key features:\n * - Runtime validation of each row as it's accessed\n * - Automatic TypeScript type inference from the Zod schema\n * - Validation errors if the data doesn't match the expected shape\n * - Ability to transform data during validation\n *\n * @example\n * ```typescript\n * // Define a schema for your data\n * const userSchema = z.object({\n *   id: z.number(),\n *   name: z.string(),\n *   email: z.string().email(),\n *   createdAt: z.string().transform(str => new Date(str)) // Transform string to Date\n * });\n *\n * // The type is automatically inferred from the schema\n * const {data, isLoading, error} = useDuckDbQuery(\n *   userSchema,\n *   {query: 'SELECT id, name, email, created_at FROM users'}\n * );\n *\n * if (isLoading) return <div>Loading...</div>;\n * if (error) {\n *   // Error will be a ZodError if validation fails\n *   if (error instanceof z.ZodError) {\n *     return <div>Validation Error: {error.errors[0].message}</div>;\n *   }\n *   return <div>Error: {error.message}</div>;\n * }\n * if (!data) return null;\n *\n * // Rows are validated and transformed according to the schema\n * const user = data.getRow(0);\n * console.log(user.createdAt.toISOString()); // createdAt is now a Date object\n * ```\n *\n * @template Schema The Zod schema type that defines the shape and validation of each row\n * @param schema A Zod schema that defines the expected shape and validation rules for each row\n * @param options Configuration object containing the query and execution control\n * @returns Object containing the validated query result, loading state, and any error\n */\nexport function useDuckDbQuery<Schema extends z.ZodType>(\n  schema: Schema,\n  options: {\n    query: string;\n    enabled?: boolean;\n  },\n): {\n  data: DuckDbQueryResult<z.infer<Schema>> | undefined;\n  error: Error | null;\n  isLoading: boolean;\n};\n\n/**\n * Implementation of useDuckDbQuery that handles both overloads\n */\nexport function useDuckDbQuery<Row, Schema extends z.ZodType = z.ZodType>(\n  schemaOrOptions: Schema | {query: string; enabled?: boolean},\n  maybeOptions?: {query: string; enabled?: boolean},\n) {\n  // Determine if we're using the schema overload\n  const hasSchema = maybeOptions !== undefined;\n  const options = hasSchema\n    ? maybeOptions\n    : (schemaOrOptions as {query: string; enabled?: boolean});\n  const schema = hasSchema ? (schemaOrOptions as Schema) : undefined;\n\n  const [data, setData] = useState<DuckDbQueryResult<Row> | undefined>(\n    undefined,\n  );\n  const [error, setError] = useState<Error | null>(null);\n  const [isLoading, setIsLoading] = useState(false);\n\n  useEffect(() => {\n    let isMounted = true;\n\n    const fetchData = async () => {\n      if (!options.enabled && options.enabled !== undefined) {\n        return;\n      }\n\n      setIsLoading(true);\n      setError(null);\n\n      try {\n        const duckDb = await getDuckDb();\n        const result = await duckDb.conn.query(options.query);\n\n        // Create a row accessor that optionally validates with the schema\n        const rowAccessor = createTypedRowAccessor<Row>({\n          arrowTable: result,\n          validate: schema ? (row: unknown) => schema.parse(row) : undefined,\n        });\n\n        if (isMounted) {\n          setData(rowAccessor);\n        }\n      } catch (err) {\n        if (isMounted) {\n          setError(err instanceof Error ? err : new Error(String(err)));\n        }\n      } finally {\n        if (isMounted) {\n          setIsLoading(false);\n        }\n      }\n    };\n\n    fetchData();\n\n    return () => {\n      isMounted = false;\n    };\n  }, [options.query, options.enabled]);\n\n  return {\n    data,\n    error,\n    isLoading,\n  };\n}\n"]}