@sqlrooms/duckdb 0.6.0 → 0.8.0

package/README.md

@@ -0,0 +1,172 @@
+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,3 +1,7 @@
+/**
+ * {@include ../README.md}
+ * @packageDocumentation
+ */
 export * from './duckdb';
 export * from './types';
 export * from './useDuckDb';

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,UAAU,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,3 +1,7 @@
+/**
+ * {@include ../README.md}
+ * @packageDocumentation
+ */
 export * from './duckdb';
 export * from './types';
 export * from './useDuckDb';

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,UAAU,CAAC","sourcesContent":["export * from './duckdb';\nexport * from './types';\nexport * from './useDuckDb';\nexport * from './exportToCsv';\nexport * from './arrow-utils';\nexport * from './useSql';\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/useDuckDb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDuckDb.d.ts","sourceRoot":"","sources":["../src/useDuckDb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,qBAAqB,CAAC;AAC9C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAC,SAAS,EAAc,MAAM,SAAS,CAAC;AAG/C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,MAAM,MAAM,MAAM,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,qBAAqB,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAeF,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;gBAChC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;IAWlE,iBAAiB;CAIlB;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,kBAAY,CAAC;AAErC,wBAAsB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CA2EjD;AAKD;;GAEG;AACH,eAAO,MAAM,WAAW,kBAAY,CAAC;AAErC,wBAAgB,SAAS,IAAI,MAAM,CAYlC;AAED,eAAO,MAAM,iBAAiB,SAAU,MAAM,YAKjB,CAAC;AAE9B,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,KAAK,CAAC,KAAK,EAChB,MAAM,GAAE,MAAM,GAAG,MAAU,EAC3B,KAAK,SAAI,GACR,MAAM,CASR;AAED,eAAO,MAAM,SAAS,QAAS,OAAO,WAErC,CAAC;AAEF,eAAO,MAAM,QAAQ,OAAQ,MAAM,WAMlC,CAAC;AAEF,wBAAsB,aAAa,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYtE;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,SAAS,GACd,OAAO,CAAC,SAAS,CAAC,CAmBpB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,SAAS,GACd,OAAO,CAAC,SAAS,EAAE,CAAC,CAOtB;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,SAAS,GACd,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiClE;AAED,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhE;AAED,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3D;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAGlD"}
+{"version":3,"file":"useDuckDb.d.ts","sourceRoot":"","sources":["../src/useDuckDb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,qBAAqB,CAAC;AAC9C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAC,SAAS,EAAc,MAAM,SAAS,CAAC;AAG/C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,MAAM,MAAM,MAAM,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,qBAAqB,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAeF,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;gBAChC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;IAWlE,iBAAiB;CAIlB;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,kBAAY,CAAC;AAErC,wBAAsB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CA2EjD;AAKD;;GAEG;AACH,eAAO,MAAM,WAAW,kBAAY,CAAC;AAErC,wBAAgB,SAAS,IAAI,MAAM,CAYlC;AAED,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,YAKjB,CAAC;AAE9B,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,KAAK,CAAC,KAAK,EAChB,MAAM,GAAE,MAAM,GAAG,MAAU,EAC3B,KAAK,SAAI,GACR,MAAM,CASR;AAED,eAAO,MAAM,SAAS,GAAI,KAAK,OAAO,WAErC,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,IAAI,MAAM,WAMlC,CAAC;AAEF,wBAAsB,aAAa,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYtE;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,SAAS,GACd,OAAO,CAAC,SAAS,CAAC,CAmBpB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,SAAS,GACd,OAAO,CAAC,SAAS,EAAE,CAAC,CAOtB;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,SAAS,GACd,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiClE;AAED,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhE;AAED,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3D;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAGlD"}

package/dist/useSql.d.ts

@@ -51,8 +51,10 @@ export type DuckDbQueryResult<T> = UseSqlQueryResult<T>;
  *   userSchema,
  *   {query: 'SELECT id, name, email, created_at as createdAt FROM users'}
  * );
+ * ```
  *
- * // Error handling is the same for both approaches
+ * ## Error Handling
+ * ```typescript
  * if (isLoading) return <div>Loading...</div>;
  * if (error) {
  *   // With Zod, you can catch validation errors specifically
@@ -62,29 +64,9 @@ export type DuckDbQueryResult<T> = UseSqlQueryResult<T>;
  *   return <div>Error: {error.message}</div>;
  * }
  * if (!data) return null;
- *
- * // Accessing data works the same way for both approaches
- * // 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})`);
- * }
- *
- * // With Zod schema, transformed fields are available
- * // for (const user of validatedData.rows()) {
- * //   console.log(`Created: ${user.createdAt.toISOString()}`); // createdAt is a Date object
- * // }
- *
- * // Get all rows as an array
- * const allUsers = data.toArray();
  * ```
  *
- * ## Performance and Advanced Operations
+ * ## Data Access Methods
  *
  * There are several ways to access data with different performance characteristics:
  *
@@ -92,22 +74,26 @@ export type DuckDbQueryResult<T> = UseSqlQueryResult<T>;
  * - Provides type safety and validation
  * - Converts data to JavaScript objects
  * - Slower for large datasets due to object creation and validation
- * - Zod validation adds additional overhead but ensures data correctness
  *
  * ```typescript
- * // Iterate through all rows with the iterator (recommended)
- * for (const row of data.rows()) {
- *   console.log(row.name);
+ * // Iterate through rows using the rows() iterator (recommended)
+ * for (const user of data.rows()) {
+ *   console.log(user.name, user.email);
  * }
  *
- * // Access rows with a traditional for loop
+ * // Traditional for loop with index access
  * for (let i = 0; i < data.length; i++) {
- *   const row = data.getRow(i);
- *   console.log(`Row ${i}: ${row.name}`);
+ *   const user = data.getRow(i);
+ *   console.log(`User ${i}: ${user.name} (${user.email})`);
  * }
  *
  * // Get all rows as an array
- * const allRows = data.toArray();
+ * 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
@@ -126,9 +112,9 @@ export type DuckDbQueryResult<T> = UseSqlQueryResult<T>;
  * }
  *
  * // 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"
- * // });
+ * const { data } = useSql<User>({
+ *   query: "SELECT * FROM users WHERE age > 30"
+ * });
  * ```
  *
  * ### 3. Using Flechette for Advanced Operations
@@ -141,7 +127,6 @@ export type DuckDbQueryResult<T> = UseSqlQueryResult<T>;
  * import { tableFromIPC } from '@uwdata/flechette';
  *
  * // Convert Arrow table to Flechette table
- * // Note: This serialization step creates a copy of the data
  * const serializedData = data.arrowTable.serialize();
  * const flechetteTable = tableFromIPC(serializedData);
  *
@@ -158,7 +143,6 @@ export type DuckDbQueryResult<T> = UseSqlQueryResult<T>;
  * });
  *
  * // For large datasets, consider memory management
- * // Once you're done with the Arrow data, you can free the memory
  * serializedData = null; // Allow garbage collection of the serialized data
  * ```
  *

package/dist/useSql.d.ts.map

@@ -1 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4JG;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"}
+{"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/useSql.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSql.js","sourceRoot":"","sources":["../src/useSql.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 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 * // Error handling is the same for both approaches\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 * // Accessing data works the same way for both approaches\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 * // 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 * // Get all rows as an array\n * const allUsers = data.toArray();\n * ```\n *\n * ## Performance and Advanced Operations\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 * - Zod validation adds additional overhead but ensures data correctness\n *\n * ```typescript\n * // Iterate through all rows with the iterator (recommended)\n * for (const row of data.rows()) {\n *   console.log(row.name);\n * }\n *\n * // Access rows with a traditional for loop\n * for (let i = 0; i < data.length; i++) {\n *   const row = data.getRow(i);\n *   console.log(`Row ${i}: ${row.name}`);\n * }\n *\n * // Get all rows as an array\n * const allRows = data.toArray();\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 * // Note: This serialization step creates a copy of the data\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 * // Once you're done with the Arrow data, you can free the memory\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"]}
+{"version":3,"file":"useSql.js","sourceRoot":"","sources":["../src/useSql.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 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.6.0",
+  "version": "0.8.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.js",
@@ -24,7 +24,7 @@
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@sqlrooms/jest-config": "0.6.0",
+    "@sqlrooms/jest-config": "0.8.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": "f46dfe6b5d135e1a039b49b3ba71cda7150eab0f"
+  "gitHead": "99b46a96ab900e6b005bcd30cfbfe7b3c9d51f8d"
 }