@hpcc-js/wasm-duckdb 1.13.1 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hpcc-js/wasm-duckdb",
-  "version": "1.13.1",
+  "version": "1.15.0",
   "description": "hpcc-js - WASM DuckDB",
   "type": "module",
   "exports": {
@@ -38,7 +38,7 @@
     "update-major": "npx -y npm-check-updates -u"
   },
   "devDependencies": {
-    "@hpcc-js/esbuild-plugins": "1.7.0",
+    "@hpcc-js/esbuild-plugins": "1.8.0",
     "@hpcc-js/wasm-util": "1.0.0"
   },
   "keywords": [
@@ -55,5 +55,5 @@
   },
   "homepage": "https://hpcc-systems.github.io/hpcc-js-wasm/",
   "license": "Apache-2.0",
-  "gitHead": "11395f5acfc865accde71905509bb45d5c79b11b"
+  "gitHead": "81504905bd26f44c1e68b31760269dee081c0cbb"
 }

package/src/duckdb.ts

@@ -91,20 +91,59 @@ const textEncoder = new TextEncoder();
  * @see [DuckDB Documentation](https://duckdb.org/docs/)
  * @see [DuckDB GitHub](https://github.com/duckdb/duckdb)
  */
-
-
-
-export class DuckDB extends MainModuleEx<MainModule> {
+export class DuckDB extends MainModuleEx<MainModule> implements Disposable {
 
     db: CPPDuckDB
 
     private constructor(_module: MainModule) {
         super(_module);
         this.db = this._module.create()!;
+        // Special home directory for web_user (needed for some extensions)
         const { FS_createPath } = this._module;
         FS_createPath("/", "home/web_user", true, true);
     }
 
+    /**
+     * Disposes of the DuckDB database instance and releases resources.
+     * 
+     * This method should be called when you're done using the database to free up
+     * memory and clean up resources. After calling dispose, the instance should not be used.
+     * 
+     * @example
+     * ```ts
+     * const duckdb = await DuckDB.load();
+     * const connection = duckdb.connect();
+     * // ... use the database ...
+     * connection.delete();
+     * duckdb.dispose();
+     * ```
+     * 
+     * @example Using statement (TypeScript 5.2+)
+     * ```ts
+     * {
+     *     using duckdb = await DuckDB.load();
+     *     const connection = duckdb.connect();
+     *     // ... use the database ...
+     *     connection.delete();
+     * } // duckdb.dispose() is called automatically
+     * ```
+     */
+    dispose(): void {
+        try {
+            this.db?.terminate();
+        } finally {
+            this.db?.delete();
+        }
+    }
+
+    /**
+     * Symbol.dispose implementation for use with `using` declarations.
+     * @internal
+     */
+    [Symbol.dispose](): void {
+        this.dispose();
+    }
+
     /**
      * Loads and initializes the DuckDB WASM module.
      * 
@@ -229,13 +268,61 @@ export class DuckDB extends MainModuleEx<MainModule> {
     registerFile(path: string, content: Uint8Array): void {
         const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
         const split = normalizedPath.lastIndexOf("/");
-        const dir = split > 0 ? normalizedPath.substring(0, split) : "/";
-        if (dir.length > 1 && this._module.FS_createPath) {
-            this._module.FS_createPath(dir, true, true);
+        if (split > 0) {
+            const dir = normalizedPath.substring(0, split);
+            const parts = dir.split("/");
+            let currentPath = "/";
+            for (const part of parts) {
+                if (part && this._module.FS_createPath) {
+                    this._module.FS_createPath(currentPath, part, true, true);
+                    currentPath = currentPath === "/" ? "/" + part : currentPath + "/" + part;
+                }
+            }
         }
         this._module.FS_createDataFile(normalizedPath, undefined, content, true, true, true);
     }
 
+    /**
+     * Unregisters and removes a file from the virtual file system.
+     * 
+     * This removes a file that was previously registered using {@link registerFile} or
+     * {@link registerFileString}. Once unregistered, the file will no longer be accessible
+     * to DuckDB queries.
+     * 
+     * The path is normalized to remove leading slashes before removal.
+     * 
+     * @param path - The path of the file to remove (e.g., "data/users.csv")
+     * 
+     * @example
+     * ```ts
+     * const duckdb = await DuckDB.load();
+     * 
+     * // Register a file
+     * duckdb.registerFileString("temp.csv", "id,name\n1,Alice");
+     * 
+     * const connection = duckdb.connect();
+     * let result = connection.query("SELECT * FROM read_csv_auto('temp.csv')");
+     * console.log(result.rowCount()); // 1
+     * result.delete();
+     * 
+     * // Unregister the file
+     * duckdb.unregisterFile("temp.csv");
+     * 
+     * // File is no longer accessible
+     * try {
+     *     result = connection.query("SELECT * FROM read_csv_auto('temp.csv')");
+     * } catch (error) {
+     *     console.error("File not found"); // Error: file not accessible
+     * }
+     * 
+     * connection.delete();
+     * ```
+     */
+    unregisterFile(path: string): void {
+        const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+        this._module.FS_unlink(normalizedPath);
+    }
+
     /**
      * Registers a text file in the virtual file system.
      * 

package/types/duckdb.d.ts

@@ -85,9 +85,40 @@ import { MainModuleEx } from "@hpcc-js/wasm-util";
  * @see [DuckDB Documentation](https://duckdb.org/docs/)
  * @see [DuckDB GitHub](https://github.com/duckdb/duckdb)
  */
-export declare class DuckDB extends MainModuleEx<MainModule> {
+export declare class DuckDB extends MainModuleEx<MainModule> implements Disposable {
     db: CPPDuckDB;
     private constructor();
+    /**
+     * Disposes of the DuckDB database instance and releases resources.
+     *
+     * This method should be called when you're done using the database to free up
+     * memory and clean up resources. After calling dispose, the instance should not be used.
+     *
+     * @example
+     * ```ts
+     * const duckdb = await DuckDB.load();
+     * const connection = duckdb.connect();
+     * // ... use the database ...
+     * connection.delete();
+     * duckdb.dispose();
+     * ```
+     *
+     * @example Using statement (TypeScript 5.2+)
+     * ```ts
+     * {
+     *     using duckdb = await DuckDB.load();
+     *     const connection = duckdb.connect();
+     *     // ... use the database ...
+     *     connection.delete();
+     * } // duckdb.dispose() is called automatically
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Symbol.dispose implementation for use with `using` declarations.
+     * @internal
+     */
+    [Symbol.dispose](): void;
     /**
      * Loads and initializes the DuckDB WASM module.
      *
@@ -190,6 +221,43 @@ export declare class DuckDB extends MainModuleEx<MainModule> {
      * ```
      */
     registerFile(path: string, content: Uint8Array): void;
+    /**
+     * Unregisters and removes a file from the virtual file system.
+     *
+     * This removes a file that was previously registered using {@link registerFile} or
+     * {@link registerFileString}. Once unregistered, the file will no longer be accessible
+     * to DuckDB queries.
+     *
+     * The path is normalized to remove leading slashes before removal.
+     *
+     * @param path - The path of the file to remove (e.g., "data/users.csv")
+     *
+     * @example
+     * ```ts
+     * const duckdb = await DuckDB.load();
+     *
+     * // Register a file
+     * duckdb.registerFileString("temp.csv", "id,name\n1,Alice");
+     *
+     * const connection = duckdb.connect();
+     * let result = connection.query("SELECT * FROM read_csv_auto('temp.csv')");
+     * console.log(result.rowCount()); // 1
+     * result.delete();
+     *
+     * // Unregister the file
+     * duckdb.unregisterFile("temp.csv");
+     *
+     * // File is no longer accessible
+     * try {
+     *     result = connection.query("SELECT * FROM read_csv_auto('temp.csv')");
+     * } catch (error) {
+     *     console.error("File not found"); // Error: file not accessible
+     * }
+     *
+     * connection.delete();
+     * ```
+     */
+    unregisterFile(path: string): void;
     /**
      * Registers a text file in the virtual file system.
      *

package/types/duckdblib.d.ts

@@ -127,6 +127,7 @@ export interface Connection extends ClassHandle {
   getQueryProgress(): number;
   prepare(_0: EmbindString): PreparedStatement | null;
   query(_0: EmbindString): MaterializedQueryResult | null;
+  queryToJSON(_0: EmbindString): string;
 }
 
 export interface DuckDB extends ClassHandle {