@sqlrooms/duckdb-core 0.26.1-rc.5

package/dist/DuckDbConnector.d.ts

@@ -0,0 +1,312 @@
+import { LoadFileOptions, StandardLoadOptions } from '@sqlrooms/room-config';
+import * as arrow from 'apache-arrow';
+import { TypeMap } from 'apache-arrow';
+/**
+ * Options for query execution
+ */
+export interface QueryOptions {
+    /**
+     * Optional external abort signal for coordinated cancellation.
+     * When provided, the query will be cancelled if this signal is aborted.
+     * This enables powerful composition patterns like cancelling multiple
+     * queries together or integrating with other cancellable operations.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Handle for managing query execution and cancellation.
+ *
+ * It is **Promise-like**, so you can either:
+ *
+ *  • `await handle` – the most ergonomic form, or
+ *  • `await handle.result` – kept for backwards-compatibility.
+ *
+ * Additional capabilities:
+ *  • Standard Promise API: `.then()`, `.catch()`, `.finally()`
+ *  • `handle.cancel()` – cancel the running query.
+ *  • `handle.signal` – `AbortSignal` that fires when the query is cancelled.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * const handle = connector.query('SELECT * FROM table');
+ * const table = await handle; // no .result needed
+ *
+ * // With cancellation
+ * const controller = new AbortController();
+ * const handle = connector.query('SELECT * FROM large_table', { signal: controller.signal });
+ * setTimeout(() => controller.abort(), 5000);
+ *
+ * // Manual cancel via the handle
+ * const h = connector.query('SELECT * FROM table');
+ * await someCondition;
+ * await h.cancel();
+ *
+ * // Composable cancellation (multiple queries, one controller)
+ * const controller = new AbortController();
+ * const h1 = connector.query('SELECT * FROM table1', { signal: controller.signal });
+ * const h2 = connector.query('SELECT * FROM table2', { signal: controller.signal });
+ * // Later...
+ * controller.abort(); // Cancels h1 and h2 together
+ *
+ * // Using Promise utilities
+ * const [t1, t2] = await Promise.all([
+ *   connector.query('select 1'),
+ *   connector.query('select 2')
+ * ]);
+ * ```
+ */
+export type QueryHandle<T = any> = PromiseLike<T> & {
+    /** Promise that resolves with query results */
+    result: Promise<T>;
+    /**
+     * Method to cancel the query with optional cleanup.
+     * This provides a clean abstraction over the underlying cancellation mechanism.
+     */
+    cancel: () => Promise<void>;
+    /**
+     * Read-only access to the abort signal for composability.
+     *
+     * Key benefits:
+     * - **Event-driven**: Listen for abort events to update UI or perform cleanup
+     * - **Integration**: Use with other Web APIs like fetch() that accept AbortSignal
+     * - **Status checking**: Check if query is already cancelled with signal.aborted
+     *
+     * @example
+     * ```typescript
+     * // Listen for cancellation events
+     * handle.signal.addEventListener('abort', () => {
+     *   console.log('Query cancelled');
+     *   updateUI('Operation cancelled');
+     * });
+     *
+     * // Check cancellation status
+     * if (handle.signal.aborted) {
+     *   console.log('Query was already cancelled');
+     * }
+     *
+     * // Use with other APIs
+     * const response = await fetch('/api/data', { signal: handle.signal });
+     * ```
+     */
+    signal: AbortSignal;
+    /** Attach a callback for only the rejection of the Promise */
+    catch: Promise<T>['catch'];
+    /** Attach a callback that's invoked when the Promise is settled (fulfilled or rejected) */
+    finally: Promise<T>['finally'];
+};
+/**
+ * DuckDB connector interface with advanced query cancellation support
+ *
+ * This interface provides a hybrid approach that combines the simplicity of method-based
+ * cancellation with the composability of Web Standards (AbortController/AbortSignal).
+ *
+ * ## Key Benefits of This Design
+ *
+ * ### 🔗 Composability
+ * Cancel multiple queries with a single controller:
+ * ```typescript
+ * const controller = new AbortController();
+ * const query1 = connector.query('SELECT * FROM table1', { signal: controller.signal });
+ * const query2 = connector.query('SELECT * FROM table2', { signal: controller.signal });
+ * controller.abort(); // Cancels both queries
+ * ```
+ *
+ * ### 🌐 Integration with Web APIs
+ * Use the same signal for queries and HTTP requests:
+ * ```typescript
+ * const controller = new AbortController();
+ * const queryHandle = connector.query('SELECT * FROM table', { signal: controller.signal });
+ * const response = await fetch('/api/data', { signal: controller.signal });
+ * // controller.abort() cancels both the query and the HTTP request
+ * ```
+ *
+ * ### 🎛️ Flexibility
+ * Simple usage when you don't need external control, advanced when you do:
+ * ```typescript
+ * // Simple - internal cancellation management
+ * const handle = connector.query('SELECT * FROM table');
+ * handle.cancel();
+ *
+ * // Advanced - external cancellation control
+ * const controller = new AbortController();
+ * const handle = connector.query('SELECT * FROM table', { signal: controller.signal });
+ * controller.abort();
+ * ```
+ *
+ * ### 📡 Event-Driven
+ * React to cancellation events for better UX:
+ * ```typescript
+ * handle.signal.addEventListener('abort', () => {
+ *   showNotification('Query cancelled');
+ *   hideLoadingSpinner();
+ * });
+ * ```
+ *
+ * ### ⏱️ Timeout Support
+ * Built-in timeout capability with manual override:
+ * ```typescript
+ * const timeoutController = new AbortController();
+ * setTimeout(() => timeoutController.abort(), 30000); // 30s timeout
+ *
+ * const handle = connector.query('SELECT * FROM large_table', {
+ *   signal: timeoutController.signal
+ * });
+ *
+ * // User can still cancel manually
+ * cancelButton.onclick = () => timeoutController.abort();
+ * ```
+ *
+ * ### 🏗️ Signal Composition
+ * Combine multiple cancellation sources:
+ * ```typescript
+ * function combineSignals(...signals: AbortSignal[]): AbortSignal {
+ *   const controller = new AbortController();
+ *   signals.forEach(signal => {
+ *     if (signal.aborted) controller.abort();
+ *     else signal.addEventListener('abort', () => controller.abort());
+ *   });
+ *   return controller.signal;
+ * }
+ *
+ * const userSignal = userController.signal;
+ * const timeoutSignal = createTimeoutSignal(30000);
+ * const combinedSignal = combineSignals(userSignal, timeoutSignal);
+ *
+ * const handle = connector.query('SELECT * FROM table', { signal: combinedSignal });
+ * ```
+ */
+export interface DuckDbConnector {
+    /**
+     * Initialize the connector.
+     * The function returns a promise that resolves when the connector is initialized.
+     * Calling the initialize() function multiple times should not restart the initialization.
+     * See BaseDuckDbConnector for an implementation example.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Destroy the connector and clean up resources
+     */
+    destroy(): Promise<void>;
+    /**
+     * Execute a SQL query without returning a result
+     *
+     * @param sql SQL query to execute
+     * @param options Optional query options including abort signal for coordinated cancellation
+     * @returns QueryHandle containing:
+     * - result: Promise that resolves when execution completes
+     * - cancel: Method to cancel the query with cleanup
+     * - signal: AbortSignal for composability with other cancellable operations
+     *
+     * @example
+     * ```typescript
+     * // Simple execution
+     * const handle = connector.execute('CREATE TABLE test AS SELECT * FROM source');
+     * await handle.result;
+     *
+     * // With external cancellation control
+     * const controller = new AbortController();
+     * const handle = connector.execute('DROP TABLE large_table', {
+     *   signal: controller.signal
+     * });
+     *
+     * // Cancel if it takes too long
+     * setTimeout(() => controller.abort(), 5000);
+     * ```
+     */
+    execute(sql: string, options?: QueryOptions): QueryHandle;
+    /**
+     * Execute a SQL query and return the result as an Arrow table
+     *
+     * @param query SQL query to execute
+     * @param options Optional query options including abort signal for coordinated cancellation
+     * @returns QueryHandle containing:
+     * - result: Promise that resolves with Arrow table
+     * - cancel: Method to cancel the query with cleanup
+     * - signal: AbortSignal for composability with other cancellable operations
+     *
+     * @example
+     * ```typescript
+     * // Basic query
+     * const handle = await connector.query('SELECT * FROM users WHERE active = true');
+     * console.log(`Found ${table.numRows} active users`);
+     *
+     * // Query with timeout
+     * const controller = new AbortController();
+     * setTimeout(() => controller.abort(), 30000); // 30s timeout
+     *
+     * const handle = connector.query('SELECT * FROM very_large_table', {
+     *   signal: controller.signal
+     * });
+     *
+     * try {
+     *   const result = await handle;
+     *   console.log('Query completed within timeout');
+     * } catch (error) {
+     *   if (error.name === 'AbortError') {
+     *     console.log('Query timed out');
+     *   }
+     * }
+     * ```
+     */
+    query<T extends TypeMap = any>(query: string, options?: QueryOptions): QueryHandle<arrow.Table<T>>;
+    /**
+     * Execute a SQL query and return the result as a JSON object
+     *
+     * @param query SQL query to execute
+     * @param options Optional query options including abort signal for coordinated cancellation
+     * @returns QueryHandle containing:
+     * - result: Promise that resolves with iterable of JSON objects
+     * - cancel: Method to cancel the query with cleanup
+     * - signal: AbortSignal for composability with other cancellable operations
+     *
+     * @example
+     * ```typescript
+     * // Simple JSON query
+     * const users = await connector.queryJson('SELECT name, email FROM users LIMIT 10');
+     * for (const user of users) {
+     *   console.log(`${user.name}: ${user.email}`);
+     * }
+     *
+     * // Coordinated cancellation with multiple operations
+     * const operationController = new AbortController();
+     *
+     * const usersHandle = connector.queryJson('SELECT * FROM users', {
+     *   signal: operationController.signal
+     * });
+     *
+     * const ordersHandle = connector.queryJson('SELECT * FROM orders', {
+     *   signal: operationController.signal
+     * });
+     *
+     * // Cancel both queries if user navigates away
+     * window.addEventListener('beforeunload', () => {
+     *   operationController.abort();
+     * });
+     * ```
+     */
+    queryJson<T = Record<string, any>>(query: string, options?: QueryOptions): QueryHandle<Iterable<T>>;
+    /**
+     * Load a file into DuckDB and create a table
+     * @param fileName - Path to the file to load
+     * @param tableName - Name of the table to create
+     * @param opts - Load options
+     */
+    loadFile(fileName: string | File, tableName: string, opts?: LoadFileOptions): Promise<void>;
+    /**
+     * Load an arrow table or an arrow IPC stream into DuckDB
+     * @param table - Arrow table or arrow IPC stream to load
+     * @param tableName - Name of the table to create
+     */
+    loadArrow(table: arrow.Table | Uint8Array, tableName: string, opts?: {
+        schema?: string;
+    }): Promise<void>;
+    /**
+     * Load JavaScript objects into DuckDB
+     * @param data - Array of objects to load
+     * @param tableName - Name of the table to create
+     * @param opts - Load options
+     */
+    loadObjects(data: Record<string, unknown>[], tableName: string, opts?: StandardLoadOptions): Promise<void>;
+}
+//# sourceMappingURL=DuckDbConnector.d.ts.map

package/dist/DuckDbConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DuckDbConnector.d.ts","sourceRoot":"","sources":["../src/DuckDbConnector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAE,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IAClD,+CAA+C;IAC/C,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEnB;;;OAGG;IACH,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAE3B,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC;IAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,KAAK,CAAC,CAAC,SAAS,OAAO,GAAG,GAAG,EAC3B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACrB,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACrB,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;OAIG;IACH,SAAS,CACP,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,UAAU,EAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAC,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;OAKG;IACH,WAAW,CACT,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,mBAAmB,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/DuckDbConnector.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=DuckDbConnector.js.map

package/dist/DuckDbConnector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DuckDbConnector.js","sourceRoot":"","sources":["../src/DuckDbConnector.ts"],"names":[],"mappings":"","sourcesContent":["import {LoadFileOptions, StandardLoadOptions} from '@sqlrooms/room-config';\nimport * as arrow from 'apache-arrow';\nimport {TypeMap} from 'apache-arrow';\n\n/**\n * Options for query execution\n */\nexport interface QueryOptions {\n  /**\n   * Optional external abort signal for coordinated cancellation.\n   * When provided, the query will be cancelled if this signal is aborted.\n   * This enables powerful composition patterns like cancelling multiple\n   * queries together or integrating with other cancellable operations.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * Handle for managing query execution and cancellation.\n *\n * It is **Promise-like**, so you can either:\n *\n *  • `await handle` – the most ergonomic form, or\n *  • `await handle.result` – kept for backwards-compatibility.\n *\n * Additional capabilities:\n *  • Standard Promise API: `.then()`, `.catch()`, `.finally()`\n *  • `handle.cancel()` – cancel the running query.\n *  • `handle.signal` – `AbortSignal` that fires when the query is cancelled.\n *\n * @example\n * ```typescript\n * // Simple usage\n * const handle = connector.query('SELECT * FROM table');\n * const table = await handle; // no .result needed\n *\n * // With cancellation\n * const controller = new AbortController();\n * const handle = connector.query('SELECT * FROM large_table', { signal: controller.signal });\n * setTimeout(() => controller.abort(), 5000);\n *\n * // Manual cancel via the handle\n * const h = connector.query('SELECT * FROM table');\n * await someCondition;\n * await h.cancel();\n *\n * // Composable cancellation (multiple queries, one controller)\n * const controller = new AbortController();\n * const h1 = connector.query('SELECT * FROM table1', { signal: controller.signal });\n * const h2 = connector.query('SELECT * FROM table2', { signal: controller.signal });\n * // Later...\n * controller.abort(); // Cancels h1 and h2 together\n *\n * // Using Promise utilities\n * const [t1, t2] = await Promise.all([\n *   connector.query('select 1'),\n *   connector.query('select 2')\n * ]);\n * ```\n */\nexport type QueryHandle<T = any> = PromiseLike<T> & {\n  /** Promise that resolves with query results */\n  result: Promise<T>;\n\n  /**\n   * Method to cancel the query with optional cleanup.\n   * This provides a clean abstraction over the underlying cancellation mechanism.\n   */\n  cancel: () => Promise<void>;\n\n  /**\n   * Read-only access to the abort signal for composability.\n   *\n   * Key benefits:\n   * - **Event-driven**: Listen for abort events to update UI or perform cleanup\n   * - **Integration**: Use with other Web APIs like fetch() that accept AbortSignal\n   * - **Status checking**: Check if query is already cancelled with signal.aborted\n   *\n   * @example\n   * ```typescript\n   * // Listen for cancellation events\n   * handle.signal.addEventListener('abort', () => {\n   *   console.log('Query cancelled');\n   *   updateUI('Operation cancelled');\n   * });\n   *\n   * // Check cancellation status\n   * if (handle.signal.aborted) {\n   *   console.log('Query was already cancelled');\n   * }\n   *\n   * // Use with other APIs\n   * const response = await fetch('/api/data', { signal: handle.signal });\n   * ```\n   */\n  signal: AbortSignal;\n\n  /** Attach a callback for only the rejection of the Promise */\n  catch: Promise<T>['catch'];\n\n  /** Attach a callback that's invoked when the Promise is settled (fulfilled or rejected) */\n  finally: Promise<T>['finally'];\n};\n\n/**\n * DuckDB connector interface with advanced query cancellation support\n *\n * This interface provides a hybrid approach that combines the simplicity of method-based\n * cancellation with the composability of Web Standards (AbortController/AbortSignal).\n *\n * ## Key Benefits of This Design\n *\n * ### 🔗 Composability\n * Cancel multiple queries with a single controller:\n * ```typescript\n * const controller = new AbortController();\n * const query1 = connector.query('SELECT * FROM table1', { signal: controller.signal });\n * const query2 = connector.query('SELECT * FROM table2', { signal: controller.signal });\n * controller.abort(); // Cancels both queries\n * ```\n *\n * ### 🌐 Integration with Web APIs\n * Use the same signal for queries and HTTP requests:\n * ```typescript\n * const controller = new AbortController();\n * const queryHandle = connector.query('SELECT * FROM table', { signal: controller.signal });\n * const response = await fetch('/api/data', { signal: controller.signal });\n * // controller.abort() cancels both the query and the HTTP request\n * ```\n *\n * ### 🎛️ Flexibility\n * Simple usage when you don't need external control, advanced when you do:\n * ```typescript\n * // Simple - internal cancellation management\n * const handle = connector.query('SELECT * FROM table');\n * handle.cancel();\n *\n * // Advanced - external cancellation control\n * const controller = new AbortController();\n * const handle = connector.query('SELECT * FROM table', { signal: controller.signal });\n * controller.abort();\n * ```\n *\n * ### 📡 Event-Driven\n * React to cancellation events for better UX:\n * ```typescript\n * handle.signal.addEventListener('abort', () => {\n *   showNotification('Query cancelled');\n *   hideLoadingSpinner();\n * });\n * ```\n *\n * ### ⏱️ Timeout Support\n * Built-in timeout capability with manual override:\n * ```typescript\n * const timeoutController = new AbortController();\n * setTimeout(() => timeoutController.abort(), 30000); // 30s timeout\n *\n * const handle = connector.query('SELECT * FROM large_table', {\n *   signal: timeoutController.signal\n * });\n *\n * // User can still cancel manually\n * cancelButton.onclick = () => timeoutController.abort();\n * ```\n *\n * ### 🏗️ Signal Composition\n * Combine multiple cancellation sources:\n * ```typescript\n * function combineSignals(...signals: AbortSignal[]): AbortSignal {\n *   const controller = new AbortController();\n *   signals.forEach(signal => {\n *     if (signal.aborted) controller.abort();\n *     else signal.addEventListener('abort', () => controller.abort());\n *   });\n *   return controller.signal;\n * }\n *\n * const userSignal = userController.signal;\n * const timeoutSignal = createTimeoutSignal(30000);\n * const combinedSignal = combineSignals(userSignal, timeoutSignal);\n *\n * const handle = connector.query('SELECT * FROM table', { signal: combinedSignal });\n * ```\n */\nexport interface DuckDbConnector {\n  /**\n   * Initialize the connector.\n   * The function returns a promise that resolves when the connector is initialized.\n   * Calling the initialize() function multiple times should not restart the initialization.\n   * See BaseDuckDbConnector for an implementation example.\n   */\n  initialize(): Promise<void>;\n\n  /**\n   * Destroy the connector and clean up resources\n   */\n  destroy(): Promise<void>;\n\n  /**\n   * Execute a SQL query without returning a result\n   *\n   * @param sql SQL query to execute\n   * @param options Optional query options including abort signal for coordinated cancellation\n   * @returns QueryHandle containing:\n   * - result: Promise that resolves when execution completes\n   * - cancel: Method to cancel the query with cleanup\n   * - signal: AbortSignal for composability with other cancellable operations\n   *\n   * @example\n   * ```typescript\n   * // Simple execution\n   * const handle = connector.execute('CREATE TABLE test AS SELECT * FROM source');\n   * await handle.result;\n   *\n   * // With external cancellation control\n   * const controller = new AbortController();\n   * const handle = connector.execute('DROP TABLE large_table', {\n   *   signal: controller.signal\n   * });\n   *\n   * // Cancel if it takes too long\n   * setTimeout(() => controller.abort(), 5000);\n   * ```\n   */\n  execute(sql: string, options?: QueryOptions): QueryHandle;\n\n  /**\n   * Execute a SQL query and return the result as an Arrow table\n   *\n   * @param query SQL query to execute\n   * @param options Optional query options including abort signal for coordinated cancellation\n   * @returns QueryHandle containing:\n   * - result: Promise that resolves with Arrow table\n   * - cancel: Method to cancel the query with cleanup\n   * - signal: AbortSignal for composability with other cancellable operations\n   *\n   * @example\n   * ```typescript\n   * // Basic query\n   * const handle = await connector.query('SELECT * FROM users WHERE active = true');\n   * console.log(`Found ${table.numRows} active users`);\n   *\n   * // Query with timeout\n   * const controller = new AbortController();\n   * setTimeout(() => controller.abort(), 30000); // 30s timeout\n   *\n   * const handle = connector.query('SELECT * FROM very_large_table', {\n   *   signal: controller.signal\n   * });\n   *\n   * try {\n   *   const result = await handle;\n   *   console.log('Query completed within timeout');\n   * } catch (error) {\n   *   if (error.name === 'AbortError') {\n   *     console.log('Query timed out');\n   *   }\n   * }\n   * ```\n   */\n  query<T extends TypeMap = any>(\n    query: string,\n    options?: QueryOptions,\n  ): QueryHandle<arrow.Table<T>>;\n\n  /**\n   * Execute a SQL query and return the result as a JSON object\n   *\n   * @param query SQL query to execute\n   * @param options Optional query options including abort signal for coordinated cancellation\n   * @returns QueryHandle containing:\n   * - result: Promise that resolves with iterable of JSON objects\n   * - cancel: Method to cancel the query with cleanup\n   * - signal: AbortSignal for composability with other cancellable operations\n   *\n   * @example\n   * ```typescript\n   * // Simple JSON query\n   * const users = await connector.queryJson('SELECT name, email FROM users LIMIT 10');\n   * for (const user of users) {\n   *   console.log(`${user.name}: ${user.email}`);\n   * }\n   *\n   * // Coordinated cancellation with multiple operations\n   * const operationController = new AbortController();\n   *\n   * const usersHandle = connector.queryJson('SELECT * FROM users', {\n   *   signal: operationController.signal\n   * });\n   *\n   * const ordersHandle = connector.queryJson('SELECT * FROM orders', {\n   *   signal: operationController.signal\n   * });\n   *\n   * // Cancel both queries if user navigates away\n   * window.addEventListener('beforeunload', () => {\n   *   operationController.abort();\n   * });\n   * ```\n   */\n  queryJson<T = Record<string, any>>(\n    query: string,\n    options?: QueryOptions,\n  ): QueryHandle<Iterable<T>>;\n\n  /**\n   * Load a file into DuckDB and create a table\n   * @param fileName - Path to the file to load\n   * @param tableName - Name of the table to create\n   * @param opts - Load options\n   */\n  loadFile(\n    fileName: string | File,\n    tableName: string,\n    opts?: LoadFileOptions,\n  ): Promise<void>;\n\n  /**\n   * Load an arrow table or an arrow IPC stream into DuckDB\n   * @param table - Arrow table or arrow IPC stream to load\n   * @param tableName - Name of the table to create\n   */\n  loadArrow(\n    table: arrow.Table | Uint8Array,\n    tableName: string,\n    opts?: {schema?: string},\n  ): Promise<void>;\n\n  /**\n   * Load JavaScript objects into DuckDB\n   * @param data - Array of objects to load\n   * @param tableName - Name of the table to create\n   * @param opts - Load options\n   */\n  loadObjects(\n    data: Record<string, unknown>[],\n    tableName: string,\n    opts?: StandardLoadOptions,\n  ): Promise<void>;\n}\n"]}

package/dist/arrow-utils.d.ts

@@ -0,0 +1,8 @@
+import * as arrow from 'apache-arrow';
+/**
+ * Converts an Arrow table to a JSON-compatible array of objects
+ * @see https://duckdb.org/docs/api/wasm/query.html#arrow-table-to-json
+ * @see https://github.com/apache/arrow/issues/37856
+ */
+export declare function arrowTableToJson(table: arrow.Table): Record<string, unknown>[];
+//# sourceMappingURL=arrow-utils.d.ts.map

package/dist/arrow-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrow-utils.d.ts","sourceRoot":"","sources":["../src/arrow-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAQ3B"}

package/dist/arrow-utils.js

@@ -0,0 +1,28 @@
+/**
+ * Converts an Arrow table to a JSON-compatible array of objects
+ * @see https://duckdb.org/docs/api/wasm/query.html#arrow-table-to-json
+ * @see https://github.com/apache/arrow/issues/37856
+ */
+export function arrowTableToJson(table) {
+    return table.toArray().map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => {
+        return [key, convertValue(value)];
+    })));
+}
+/**
+ * Converts an Arrow table value to a JSON-compatible value
+ * @param value
+ * @returns
+ */
+function convertValue(value) {
+    if (typeof value === 'bigint') {
+        if (value >= Number.MIN_SAFE_INTEGER && value <= Number.MAX_SAFE_INTEGER) {
+            return Number(value);
+        }
+        return String(value);
+    }
+    if (typeof value === 'number') {
+        return value;
+    }
+    return String(value);
+}
+//# sourceMappingURL=arrow-utils.js.map

package/dist/arrow-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrow-utils.js","sourceRoot":"","sources":["../src/arrow-utils.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAkB;IAElB,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACjC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QACvC,OAAO,CAAC,GAAG,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,CACH,CACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,IAAI,MAAM,CAAC,gBAAgB,IAAI,KAAK,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;YACzE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC","sourcesContent":["import * as arrow from 'apache-arrow';\n\n/**\n * Converts an Arrow table to a JSON-compatible array of objects\n * @see https://duckdb.org/docs/api/wasm/query.html#arrow-table-to-json\n * @see https://github.com/apache/arrow/issues/37856\n */\nexport function arrowTableToJson(\n  table: arrow.Table,\n): Record<string, unknown>[] {\n  return table.toArray().map((row) =>\n    Object.fromEntries(\n      Object.entries(row).map(([key, value]) => {\n        return [key, convertValue(value)];\n      }),\n    ),\n  );\n}\n\n/**\n * Converts an Arrow table value to a JSON-compatible value\n * @param value\n * @returns\n */\nfunction convertValue(value: unknown) {\n  if (typeof value === 'bigint') {\n    if (value >= Number.MIN_SAFE_INTEGER && value <= Number.MAX_SAFE_INTEGER) {\n      return Number(value);\n    }\n    return String(value);\n  }\n  if (typeof value === 'number') {\n    return value;\n  }\n  return String(value);\n}\n"]}

package/dist/duckdb-utils.d.ts

@@ -0,0 +1,140 @@
+import * as arrow from 'apache-arrow';
+export type QualifiedTableName = {
+    database?: string;
+    schema?: string;
+    table: string;
+    toString: () => string;
+};
+export declare function isQualifiedTableName(tableName: string | QualifiedTableName): tableName is QualifiedTableName;
+/**
+ * Get a qualified table name from a table name, schema, and database.
+ * @param table - The name of the table.
+ * @param schema - The schema of the table.
+ * @param database - The database of the table.
+ * @returns The qualified table name.
+ */
+export declare function makeQualifiedTableName({ database, schema, table, }: QualifiedTableName): {
+    database: string | undefined;
+    schema: string | undefined;
+    table: string;
+    toString: () => string;
+};
+/**
+ * Escapes a value for use in DuckDB SQL queries by wrapping it in single quotes
+ * and escaping any existing single quotes by doubling them.
+ *
+ * @param val - The value to escape. Will be converted to string if not already a string.
+ * @returns The escaped string value wrapped in single quotes.
+ * @example
+ * escapeVal("John's data") // Returns "'John''s data'"
+ */
+export declare const escapeVal: (val: unknown) => string;
+/**
+ * Escapes an identifier (like table or column names) for use in DuckDB SQL queries
+ * by wrapping it in double quotes and escaping any existing double quotes by doubling them.
+ * If the identifier is already properly quoted, returns it as is.
+ *
+ * @param id - The identifier string to escape
+ * @returns The escaped identifier wrapped in double quotes
+ * @example
+ * escapeId("my_table") // Returns '"my_table"'
+ * escapeId("my""table") // Returns '"my""""table"'
+ */
+export declare const escapeId: (id: string) => string;
+/**
+ * Checks if a DuckDB type string represents a numeric type.
+ * Includes INTEGER, DECIMAL, FLOAT, REAL, and DOUBLE types.
+ *
+ * @param type - The DuckDB type string to check
+ * @returns True if the type is numeric, false otherwise
+ * @example
+ * isNumericDuckType('INTEGER') // Returns true
+ * isNumericDuckType('VARCHAR') // Returns false
+ */
+export declare const isNumericDuckType: (type: string) => boolean;
+/**
+ * Extracts a numeric value from an Arrow Table at the specified column and row index.
+ * Handles both column name and index-based access. Converts BigInt values to numbers.
+ *
+ * @param res - The Arrow Table containing the data
+ * @param column - The column name or index (0-based) to read from. Defaults to first column (0)
+ * @param index - The row index (0-based) to read from. Defaults to first row (0)
+ * @returns The numeric value at the specified position, or NaN if the value is null/undefined
+ * @example
+ * const value = getColValAsNumber(table, "amount", 0)
+ */
+export declare function getColValAsNumber(res: arrow.Table, column?: string | number, index?: number): number;
+/**
+ * Function given a query and position finds the line and column of the console.error();
+ *
+ * @param query - The query to parse
+ * @param position - The position of the error
+ * @returns The line and column of the error
+ */
+export declare const getSqlErrorWithPointer: (query: string, position: number) => {
+    line: number;
+    column: number;
+    lineText: string;
+    pointerLine: string;
+    formatted: string;
+};
+/**
+ * Split a string with potentially multiple SQL queries (separated as usual by ';')
+ * into an array of queries.
+ * This implementation:
+ *  - Handles single and double quoted strings with proper escaping
+ *  - Removes all comments: line comments (--) and block comments (/* ... *\/)
+ *  - Ignores semicolons in quoted strings and comments
+ *  - Trims whitespace from queries
+ *  - Handles SQL-style escaped quotes ('' inside strings)
+ *  - Returns only non-empty queries
+ *
+ * @param input - The SQL string containing one or more statements
+ * @returns An array of SQL statements with all comments removed
+ */
+export declare function splitSqlStatements(input: string): string[];
+/**
+ * Sanitizes a SQL query by removing trailing semicolons, comments, and normalizing whitespace
+ */
+export declare function sanitizeQuery(query: string): string;
+/**
+ * Make a limit query from a query and a limit.
+ * @param query - The SELECT query to make limited.
+ * @param options - The options for the limit query.
+ * @param options.limit - The number of rows to limit the query to.
+ * @param options.offset - The number of rows to offset the query by.
+ * @param options.sanitize - Whether to sanitize the query.
+ * @returns The limited query.
+ */
+export declare function makeLimitQuery(query: string, { limit, offset, sanitize, }?: {
+    limit?: number;
+    offset?: number;
+    sanitize?: boolean;
+}): string;
+/**
+ * Result of separating the last SQL statement from preceding ones.
+ */
+export type SeparatedStatements = {
+    /** All statements except the last one */
+    precedingStatements: string[];
+    /** The last statement */
+    lastStatement: string;
+};
+/**
+ * Separates a SQL query into preceding statements and the last statement.
+ * Useful when you need to execute multiple statements but handle the last one differently
+ * (e.g., wrap it in CREATE TABLE, add LIMIT, etc.).
+ *
+ * @param query - The SQL query string containing one or more statements
+ * @returns Object containing preceding statements and the last statement
+ * @throws Error if the query contains no statements
+ */
+export declare function separateLastStatement(query: string): SeparatedStatements;
+/**
+ * Joins preceding statements with a (potentially modified) last statement into a single query.
+ * @param precedingStatements - Statements to execute before the last one
+ * @param lastStatement - The final statement (can be modified, e.g., wrapped in CREATE TABLE)
+ * @returns A single query string with all statements joined by semicolons
+ */
+export declare function joinStatements(precedingStatements: string[], lastStatement: string): string;
+//# sourceMappingURL=duckdb-utils.d.ts.map

package/dist/duckdb-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckdb-utils.d.ts","sourceRoot":"","sources":["../src/duckdb-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GACrC,SAAS,IAAI,kBAAkB,CAEjC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,MAAM,EACN,KAAK,GACN,EAAE,kBAAkB;;;;;EAWpB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,OAAO,WAErC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,GAAI,IAAI,MAAM,WAMlC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,YAKjB,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,KAAK,CAAC,KAAK,EAChB,MAAM,GAAE,MAAM,GAAG,MAAU,EAC3B,KAAK,SAAI,GACR,MAAM,CASR;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM;;;;;;CAsBrE,CAAC;AAoBF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAqG1D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,EACE,KAAW,EACX,MAAU,EACV,QAAe,GAChB,GAAE;IACD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACf,UAKP;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,yCAAyC;IACzC,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,yBAAyB;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CASxE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,mBAAmB,EAAE,MAAM,EAAE,EAC7B,aAAa,EAAE,MAAM,GACpB,MAAM,CAIR"}