feat: add better exception handling

GordonSmith · GordonSmith · commit 86ad647ed409 · 2026-01-14T11:54:55.000Z
Signed-off-by: Gordon Smith &lt;GordonJSmith@gmail.com&gt;
diff --git a/packages/base91/CMakeLists.txt b/packages/base91/CMakeLists.txt
@@ -14,6 +14,7 @@ set(EM_LINK_FLAGS
     "-sEXPORT_NAME='${CMAKE_PROJECT_NAME}'"
 
     "-fwasm-exceptions"
+    "-sEXCEPTION_STACK_TRACES=1"
     "--emit-tsd ${CMAKE_CURRENT_BINARY_DIR}/base91lib.d.ts"
 )
 string(REPLACE ";" " " LINK_FLAGS "${EM_LINK_FLAGS}")
diff --git a/packages/base91/src/base91.ts b/packages/base91/src/base91.ts
@@ -5,7 +5,7 @@ import { MainModuleEx } from "@hpcc-js/wasm-util";
 
 //  Ref:  http://base91.sourceforge.net/#a5
 
-let g_base91: Promise<Base91>;
+let g_base91: Promise<Base91> | undefined;
 
 /**
  * Base 91 WASM library, similar to Base 64 but uses more characters resulting in smaller strings.
@@ -49,8 +49,14 @@ export class Base91 extends MainModuleEx<MainModule> {
     /**
      * Unloades the compiled wasm instance.
      */
-    static unload() {
-        reset();
+    static async unload() {
+        try {
+            const base91 = await g_base91;
+            base91?._base91?.delete();
+        } finally {
+            reset();
+            g_base91 = undefined;
+        }
     }
 
     /**
diff --git a/packages/base91/tests/base91.spec.ts b/packages/base91/tests/base91.spec.ts
@@ -3,21 +3,37 @@ import { Base91 } from "@hpcc-js/wasm-base91";
 
 describe("base91", function () {
 
+    it("unload resets singleton and is idempotent", async function () {
+        await Base91.unload();
+
+        const base91a = await Base91.load();
+        expect(await Base91.load()).to.equal(base91a);
+
+        await Base91.unload();
+
+        const base91b = await Base91.load();
+        expect(base91b).to.not.equal(base91a);
+        expect(await Base91.load()).to.equal(base91b);
+
+        await Base91.unload();
+        await Base91.unload();
+    });
+
     it("version", async function () {
         let base91 = await Base91.load();
         expect(await Base91.load()).to.equal(base91);
         let v = base91.version();
         expect(v).to.be.a.string;
         expect(v).to.equal("0.6.0");
         console.log("base91 version: " + v);
-        Base91.unload();
+        await Base91.unload();
 
         base91 = await Base91.load();
         expect(await Base91.load()).to.equal(base91);
         v = base91.version();
         expect(v).to.be.a.string;
         expect(v).to.not.be.empty;
-        Base91.unload();
+        await Base91.unload();
     });
 
     it("simple", async function () {
diff --git a/packages/duckdb/CMakeLists.txt b/packages/duckdb/CMakeLists.txt
@@ -28,6 +28,7 @@ set(EM_LINK_FLAGS
     # "-sALLOW_UNIMPLEMENTED_SYSCALLS=1"
 
     "-fwasm-exceptions"
+    "-sEXCEPTION_STACK_TRACES=1"
     "--emit-tsd ${CMAKE_CURRENT_BINARY_DIR}/duckdblib.d.ts"
 )
 string(REPLACE ";" " " LINK_FLAGS "${EM_LINK_FLAGS}")
diff --git a/packages/duckdb/package.json b/packages/duckdb/package.json
@@ -27,6 +27,7 @@
     "bundle-watch": "npm run bundle-dev -- --watch",
     "build-dev": "run-p gen-types bundle-dev",
     "build": "run-p gen-types bundle",
+    "build-all": "run-s build-cpp gen-types bundle",
     "lint-skypack": "npx -y @skypack/package-check",
     "lint-eslint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
     "lint": "run-p lint-eslint",
diff --git a/packages/duckdb/src-cpp/main.cpp b/packages/duckdb/src-cpp/main.cpp
@@ -334,15 +334,15 @@ namespace ConnectionHelper
     {
         return obj.Query(query).release();
     }
-
     std::string queryToJSON(Connection &obj, const string &query)
     {
         auto result = obj.Query(query);
-        if (!result->HasError())
+        if (result->HasError())
         {
-            return MaterializedQueryResultHelper::toJSON(*result);
+            auto err = result->GetError();
+            throw std::runtime_error(err.c_str());
         }
-        return std::string();
+        return MaterializedQueryResultHelper::toJSON(*result);
     }
 }
 namespace DuckDBHelper
diff --git a/packages/duckdb/src/duckdb.ts b/packages/duckdb/src/duckdb.ts
@@ -3,7 +3,7 @@ import load, { reset } from "../../../build/packages/duckdb/duckdblib.wasm";
 import type { MainModule, DuckDB as CPPDuckDB } from "../types/duckdblib.js";
 import { MainModuleEx } from "@hpcc-js/wasm-util";
 
-let g_duckdb: Promise<DuckDB>;
+let g_duckdb: Promise<DuckDB> | undefined;
 const textEncoder = new TextEncoder();
 
 /**
@@ -91,7 +91,7 @@ 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> implements Disposable {
+export class DuckDB extends MainModuleEx<MainModule> {
 
     db: CPPDuckDB
 
@@ -103,47 +103,6 @@ export class DuckDB extends MainModuleEx<MainModule> implements Disposable {
         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.
      * 
@@ -167,7 +126,7 @@ export class DuckDB extends MainModuleEx<MainModule> implements Disposable {
                 return new DuckDB(module)
             });
         }
-        return g_duckdb;
+        return g_duckdb!;
     }
 
     /**
@@ -182,8 +141,20 @@ export class DuckDB extends MainModuleEx<MainModule> implements Disposable {
      * // The next call to DuckDB.load() will create a fresh instance
      * ```
      */
-    static unload() {
-        reset();
+    static async unload() {
+        try {
+            const duckdb = await g_duckdb;
+            if (duckdb?.db) {
+                try {
+                    duckdb.db.terminate();
+                } finally {
+                    duckdb.db.delete();
+                }
+            }
+        } finally {
+            reset();
+            g_duckdb = undefined;
+        }
     }
 
     /**
@@ -240,6 +211,27 @@ export class DuckDB extends MainModuleEx<MainModule> implements Disposable {
         return Number(this.db.numberOfThreads());
     }
 
+    getExceptionMessage(error: unknown): { type: string, message?: string } {
+        const mod: any = this._module as any;
+        try {
+            const result = mod?.getExceptionMessage?.(error);
+            if (Array.isArray(result)) {
+                return {
+                    type: result[0] ?? "",
+                    message: result[1] ?? ""
+                };
+            }
+        } catch (_err) {
+            void _err;
+        }
+
+        const err: any = error;
+        return {
+            type: err?.name ?? "Error",
+            message: typeof err?.message === "string" ? err.message : String(error)
+        };
+    }
+
     /**
      * Registers a binary file in the virtual file system.
      * 
@@ -371,5 +363,5 @@ export class DuckDB extends MainModuleEx<MainModule> implements Disposable {
         const encoded = textEncoder.encode(content);
         this.registerFile(fileName, encoded);
     }
-
 }
+
diff --git a/packages/duckdb/tests/duckdb.spec.ts b/packages/duckdb/tests/duckdb.spec.ts
@@ -1,13 +1,17 @@
-import { beforeAll, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { DuckDB } from "@hpcc-js/wasm-duckdb";
 
-describe("duckdb", () => {
+describe.sequential("duckdb", () => {
     let duckdb: DuckDB;
 
     beforeAll(async () => {
         duckdb = await DuckDB.load();
     });
 
+    afterAll(async () => {
+        await DuckDB.unload();
+    });
+
     describe("DuckDB static methods", () => {
         it("loads once and reports version", async () => {
             const secondLoad = await DuckDB.load();
@@ -826,5 +830,38 @@ FROM duckdb_extensions();
 
             con.delete();
         });
+
+        it("exception handline", () => {
+            const con = duckdb.connect();
+            try {
+                const json = con.queryToJSON("Great Big Error!");
+                JSON.parse(json);
+            } catch (e) {
+                const exception = duckdb.getExceptionMessage(e)
+                expect(exception).toBeDefined();
+                expect(exception.type).toBe("std::runtime_error");
+                expect(e).toBeDefined();
+            } finally {
+                con.delete();
+            }
+        });
+    });
+
+    describe("unload", () => {
+        it("resets singleton and is idempotent", async () => {
+            await DuckDB.unload();
+
+            const dba = await DuckDB.load();
+            expect(await DuckDB.load()).toBe(dba);
+
+            await DuckDB.unload();
+
+            const dbb = await DuckDB.load();
+            expect(dbb).not.toBe(dba);
+            expect(await DuckDB.load()).toBe(dbb);
+
+            await DuckDB.unload();
+            await DuckDB.unload();
+        });
     });
 });
diff --git a/packages/expat/CMakeLists.txt b/packages/expat/CMakeLists.txt
@@ -14,6 +14,7 @@ set(EM_LINK_FLAGS
     "-sEXPORT_NAME='${CMAKE_PROJECT_NAME}'"
 
     "-fwasm-exceptions"
+    "-sEXCEPTION_STACK_TRACES=1"
     "--emit-tsd ${CMAKE_CURRENT_BINARY_DIR}/expatlib.d.ts"
 )
 string(REPLACE ";" " " LINK_FLAGS "${EM_LINK_FLAGS}")
diff --git a/packages/expat/src/expat.ts b/packages/expat/src/expat.ts
@@ -22,7 +22,7 @@ function parseAttrs(attrs: map_string_string): Attributes {
     return retVal;
 }
 
-let g_expat: Promise<Expat>;
+let g_expat: Promise<Expat> | undefined;
 
 /**
  * Expat XML parser WASM library, provides a simplified wrapper around the Expat XML Parser library.  
@@ -77,6 +77,7 @@ export class Expat extends MainModuleEx<MainModule> {
      */
     static unload() {
         reset();
+        g_expat = undefined;
     }
 
     /**
diff --git a/packages/expat/tests/expat.spec.ts b/packages/expat/tests/expat.spec.ts
@@ -32,6 +32,22 @@ class KeywordParser extends StackParser {
 }
 
 describe("expat", function () {
+    it("unload resets singleton and is idempotent", async function () {
+        Expat.unload();
+
+        const expata = await Expat.load();
+        expect(await Expat.load()).to.equal(expata);
+
+        Expat.unload();
+
+        const expatb = await Expat.load();
+        expect(expatb).to.not.equal(expata);
+        expect(await Expat.load()).to.equal(expatb);
+
+        Expat.unload();
+        Expat.unload();
+    });
+
     it("version", async function () {
         let expat = await Expat.load();
         let v = await expat.version();
diff --git a/packages/graphviz/CMakeLists.txt b/packages/graphviz/CMakeLists.txt
@@ -22,6 +22,7 @@ set(EM_LINK_FLAGS
     "-sFILESYSTEM=1"
 
     "-fwasm-exceptions"
+    "-sEXCEPTION_STACK_TRACES=1"
     "--emit-tsd ${CMAKE_CURRENT_BINARY_DIR}/graphvizlib.d.ts"
 )
 string(REPLACE ";" " " LINK_FLAGS "${EM_LINK_FLAGS}")
diff --git a/packages/graphviz/src/graphviz.ts b/packages/graphviz/src/graphviz.ts
@@ -72,7 +72,7 @@ function createFiles(graphviz: any, _options?: Options) {
     [...options.files, ...imagesToFiles(options.images)].forEach(file => graphviz.createFile(file.path, file.data));
 }
 
-let g_graphviz: Promise<Graphviz>;
+let g_graphviz: Promise<Graphviz> | undefined;
 
 /**
  * The Graphviz layout algorithms take descriptions of graphs in a simple text language, and make diagrams in useful formats, such as images and SVG for web pages or display in an interactive graph browser.
@@ -121,6 +121,7 @@ export class Graphviz extends MainModuleEx<MainModule> {
      */
     static unload() {
         reset();
+        g_graphviz = undefined;
     }
 
     /**
diff --git a/packages/graphviz/tests/graphviz.spec.ts b/packages/graphviz/tests/graphviz.spec.ts
@@ -30,6 +30,22 @@ describe("all combos", () => {
 
 describe("graphviz", function () {
 
+    it("unload resets singleton and is idempotent", async function () {
+        Graphviz.unload();
+
+        const graphviza = await Graphviz.load();
+        expect(await Graphviz.load()).to.equal(graphviza);
+
+        Graphviz.unload();
+
+        const graphvizb = await Graphviz.load();
+        expect(graphvizb).to.not.equal(graphviza);
+        expect(await Graphviz.load()).to.equal(graphvizb);
+
+        Graphviz.unload();
+        Graphviz.unload();
+    });
+
     it("version", async function () {
         let graphviz = await Graphviz.load();
         let v = graphviz.version();
diff --git a/packages/llama/CMakeLists.txt b/packages/llama/CMakeLists.txt
diff --git a/packages/util/CMakeLists.txt b/packages/util/CMakeLists.txt
diff --git a/packages/zstd/CMakeLists.txt b/packages/zstd/CMakeLists.txt
diff --git a/packages/zstd/src/zstd.ts b/packages/zstd/src/zstd.ts
diff --git a/packages/zstd/tests/zstd.spec.ts b/packages/zstd/tests/zstd.spec.ts
diff --git a/vcpkg.json b/vcpkg.json
diff --git a/vitest-projects.ts b/vitest-projects.ts

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ set(EM_LINK_FLAGS`
`14`	`14`	`"-sEXPORT_NAME='${CMAKE_PROJECT_NAME}'"`
`15`	`15`
`16`	`16`	`"-fwasm-exceptions"`
	`17`	`+ "-sEXCEPTION_STACK_TRACES=1"`
`17`	`18`	`"--emit-tsd ${CMAKE_CURRENT_BINARY_DIR}/base91lib.d.ts"`
`18`	`19`	`)`
`19`	`20`	`string(REPLACE ";" " " LINK_FLAGS "${EM_LINK_FLAGS}")`
Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,7 @@ set(EM_LINK_FLAGS`
`28`	`28`	`# "-sALLOW_UNIMPLEMENTED_SYSCALLS=1"`
`29`	`29`
`30`	`30`	`"-fwasm-exceptions"`
	`31`	`+ "-sEXCEPTION_STACK_TRACES=1"`
`31`	`32`	`"--emit-tsd ${CMAKE_CURRENT_BINARY_DIR}/duckdblib.d.ts"`
`32`	`33`	`)`
`33`	`34`	`string(REPLACE ";" " " LINK_FLAGS "${EM_LINK_FLAGS}")`
Original file line number	Diff line number	Diff line change
`@@ -334,15 +334,15 @@ namespace ConnectionHelper`
`334`	`334`	`{`
`335`	`335`	`return obj.Query(query).release();`
`336`	`336`	`}`
`337`		`-`
`338`	`337`	`std::string queryToJSON(Connection &obj, const string &query)`
`339`	`338`	`{`
`340`	`339`	`auto result = obj.Query(query);`
`341`		`- if (!result->HasError())`
	`340`	`+ if (result->HasError())`
`342`	`341`	`{`
`343`		`- return MaterializedQueryResultHelper::toJSON(*result);`
	`342`	`+ auto err = result->GetError();`
	`343`	`+ throw std::runtime_error(err.c_str());`
`344`	`344`	`}`
`345`		`- return std::string();`
	`345`	`+ return MaterializedQueryResultHelper::toJSON(*result);`
`346`	`346`	`}`
`347`	`347`	`}`
`348`	`348`	`namespace DuckDBHelper`
Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ function parseAttrs(attrs: map_string_string): Attributes {`
`22`	`22`	`return retVal;`
`23`	`23`	`}`
`24`	`24`
`25`		`-let g_expat: Promise<Expat>;`
	`25`	`+let g_expat: Promise<Expat> \| undefined;`
`26`	`26`
`27`	`27`	`/**`
`28`	`28`	`* Expat XML parser WASM library, provides a simplified wrapper around the Expat XML Parser library.`
`@@ -77,6 +77,7 @@ export class Expat extends MainModuleEx<MainModule> {`
`77`	`77`	`*/`
`78`	`78`	`static unload() {`
`79`	`79`	`reset();`
	`80`	`+ g_expat = undefined;`
`80`	`81`	`}`
`81`	`82`
`82`	`83`	`/**`