@theqrl/hypc 0.0.2 → 0.3.1

package/README.md

@@ -12,6 +12,8 @@ To use the latest stable version of the Hyperion compiler via Node.js you can in
 npm install @theqrl/hypc
 ```
 
+It needs Node.js 22.12 or later.
+
 ### Usage on the Command-Line
 
 If this package is installed globally (`npm install -g @theqrl/hypc`), a command-line tool called `hypcjs` will be available.
@@ -30,6 +32,14 @@ Use the ``--base-path`` and ``--include-path`` options to describe the layout of
 ``--base-path`` represents the root of your own source tree while ``--include-path`` allows you to
 specify extra locations containing external code (e.g. libraries installed with a package manager).
 
+As in `hypc`, the import callback only reads files inside the base path (the working directory
+when ``--base-path`` is not given), the include paths and the directories of the files given on
+the command line. Symbolic links are resolved first. Any other import fails with
+`File outside of allowed directories.`
+If the working directory is the root of the filesystem (or of a drive on Windows) and
+``--base-path`` is not given, the working directory is not allowed, since every readable file
+would then be importable. Pass ``--base-path`` explicitly if you really need it.
+
 Note: ensure that all the files you specify on the command line are located inside the base path or
 one of the include paths.
 The compiler refers to files from outside of these directories using absolute paths.
@@ -37,7 +47,7 @@ Having absolute paths in contract metadata will result in your bytecode being re
 when it's placed in these exact absolute locations.
 
 Note: this commandline interface is not compatible with `hypc` provided by the Hyperion compiler package and thus cannot be
-used in combination with an Zond client via the `zond.compile.hyperion()` RPC method. Please refer to the
+used in combination with a QRL client via the `qrl.compile.hyperion()` RPC method. Please refer to the
 [Hyperion compiler documentation](https://theqrl.org/) for instructions to install `hypc`.
 Furthermore, the commandline interface to hypc-js provides fewer features than the binary release.
 
@@ -61,6 +71,11 @@ as a string.  It cannot be used together with callback-based, asynchronous,
 filesystem access. A workaround is to collect the names of dependencies, return
 an error, and keep re-running the compiler until all of them are resolved.
 
+A callback that throws, or that returns anything but an object with a string ``contents`` or a
+string ``error``, does not abort the compilation: the compiler reports it as the import error, for
+example ``Source "a.hyp" not found: Callback threw Error: ENOENT: no such file or directory``. An
+``error`` that is not a string, such as an ``Error`` object, is reported as the error it describes.
+
 #### Example usage without the import callback
 
 Example:
@@ -91,7 +106,7 @@ for (var contractName in output.contracts['test.hyp']) {
   console.log(
     contractName +
       ': ' +
-      output.contracts['test.hyp'][contractName].evm.bytecode.object
+      output.contracts['test.hyp'][contractName].qrvm.bytecode.object
   );
 }
 ```
@@ -136,7 +151,7 @@ for (var contractName in output.contracts['test.hyp']) {
   console.log(
     contractName +
       ': ' +
-      output.contracts['test.hyp'][contractName].evm.bytecode.object
+      output.contracts['test.hyp'][contractName].qrvm.bytecode.object
   );
 }
 ```
@@ -149,7 +164,7 @@ return either an error or the result from the solver.  A default
 ``smtchecker.js`` which exports the ``smtCallback`` function that takes 1) a
 function that takes queries and returns the solving result, and 2) a solver
 configuration object. The module ``smtsolver.js`` has a few predefined solver
-configurations, and relies on Z3, Eldarica or cvc5 being installed locally.  It
+configurations, and relies on Z3, Eldarica, cvc5 or cvc4 being installed locally.  It
 exports the list of locally found solvers and a function that invokes a given
 solver.
 
@@ -190,6 +205,18 @@ var output = JSON.parse(
 The assertion is clearly false, and an ``assertion failure`` warning
 should be returned, together with a counterexample.
 
+#### When an exception unwinds through the compiler
+
+`compile` throws when a JavaScript exception unwinds through the compiler itself, for example the
+`RangeError` of a stack overflow on deeply nested source. The compiler's cleanup does not run then,
+so the module instance the exception unwound through cannot compile again, and the next call to
+`compile` loads a fresh instance of the module, or, where none can be loaded, goes on with the same
+instance once the compiler has discarded the abandoned compilation. This needs nothing from the
+caller for the bundled compiler and for one from `loadRemoteVersion`; for a module given to
+`setupMethods`, see [Using a Legacy Version](#using-a-legacy-version). Going on with the same
+instance keeps the memory of the abandoned compilation allocated, since the compiler cannot free
+what the exception interrupted; a fresh instance does not.
+
 #### Low-level API
 
 The low-level API is as follows:
@@ -228,33 +255,50 @@ In order to compile contracts using a specific version of Hyperion, the `hypc.lo
 You can also load the "binary" manually and use `setupMethods` to create the familiar wrapper functions described above:
 `var hypc = hypc.setupMethods(require("/my/local/hypjson.js"))`.
 
-### Using the Latest Development Snapshot
+When an exception unwinds through such a module (see above), `setupMethods` loads a fresh instance
+from the module's file if `require` loaded it. Otherwise pass a function that returns a fresh
+module as the second argument, `hypc.setupMethods(hypjson, loadHypjson)`. Without one, as in a
+browser, the same instance goes on after `hyperion_reset()` has discarded the abandoned
+compilation, which compilers from 0.3.0 on support; with an older compiler, or after a WebAssembly
+trap, the next `compile` returns an error that says the module cannot be used again. Each
+compilation the same instance goes on from leaves its memory allocated in the instance, so a
+long-lived page that sees `compile` throw more than rarely should load a fresh module itself.
+
+### Using the Latest Release
 
-By default, the npm version is only created for releases. This prevents people from deploying contracts with non-release versions because they are less stable and harder to verify. If you would like to use the latest development snapshot (at your own risk!), you may use the following example code.
+`loadRemoteVersion('latest', …)` loads the latest release in the
+[release list](https://binaries.theqrl.org/bin/list.json), which can be newer than the compiler that
+your installed copy of this package bundles.
 
 ```javascript
 var hypc = require('@theqrl/hypc');
 
-// getting the development snapshot
-hypc.loadRemoteVersion('latest', function(err, hypcSnapshot) {
+// getting the latest release
+hypc.loadRemoteVersion('latest', function(err, hypcLatest) {
   if (err) {
     // An error was encountered, display and quit
   } else {
-    // NOTE: Use `hypcSnapshot` here with the same interface `hypc` has
+    // NOTE: Use `hypcLatest` here with the same interface `hypc` has
     // For example:
-    const output = hypcSnapshot.compile(/* ... */)
+    const output = hypcLatest.compile(/* ... */)
   }
 });
 ```
 
-The version **must** be in the long format.
-Thus, if you would like to use version `v0.8.17` you need to include the commit hash of the release.
-You can extract the long version string for each version from the [publicly available release list](https://binaries.theqrl.org/bin/list.json).
+The version is `latest`, a release such as `0.2.0`, or a build in the long format, which includes
+the commit hash, such as `v0.2.0+commit.e36a0aea`. The [publicly available release list](https://binaries.theqrl.org/bin/list.json)
+has every version.
 
 ```javascript
-hypc.loadRemoteVersion('v0.8.17+commit.8df45f5f', function(err, hypcSnapshot) { /* ... */ });
+hypc.loadRemoteVersion('v0.2.0+commit.e36a0aea', function(err, hypcRemote) { /* ... */ });
 ```
 
+`loadRemoteVersion` looks the version up in that list and downloads the build from
+`binaries.theqrl.org`. It runs the build only if its keccak256 and sha256 match the list, and
+otherwise passes an error to the callback. It follows redirects only to `https` URLs on the same
+host, and stops reading a build larger than 64 MiB. A build that fails to load also reaches the
+callback as an error.
+
 ### Linking Bytecode
 
 When using libraries, the resulting bytecode will contain placeholders for the real addresses of the referenced libraries. These have to be updated, via a process called linking, before deploying the contract.
@@ -266,9 +310,12 @@ The `linkBytecode` method provides a simple helper for linking:
 ```javascript
 var linker = require('@theqrl/hypc/linker');
 
-bytecode = linker.linkBytecode(bytecode, { MyLibrary: '0x123456...' });
+bytecode = linker.linkBytecode(bytecode, { MyLibrary: 'Q123456...' });
 ```
 
+An address is `Q` followed by 128 hex digits. As in the compiler's `settings.libraries`, an address
+in mixed case must carry the address checksum; one in all lower case or all upper case does not.
+
 As of Hyperion 0.4.11 the compiler supports [standard JSON input and output](https://theqrl.org) which outputs a _link references_ map. This gives a map of library names to offsets in the bytecode to replace the addresses at. It also doesn't have the limitation on library file and contract name lengths.
 
 There is a method available in the `linker` module called `findLinkReferences` which can find such link references in bytecode produced by an older compiler:

package/abi.js

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 const semver = __importStar(require("semver"));
 function update(compilerVersion, abi) {
     let hasConstructor = false;

package/bindings/compile.js

@@ -3,19 +3,66 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setupCompile = void 0;
+exports.setupCompile = setupCompile;
 const assert_1 = __importDefault(require("assert"));
 const helpers_1 = require("../common/helpers");
 const helpers_2 = require("./helpers");
-function setupCompile(hypJson, core) {
+/**
+ * @param hypJson The Emscripten compiled Hyperion object.
+ * @param core The core bound Hyperion methods.
+ * @param onEscapedException Called with the exception when a JavaScript exception has unwound
+ *   through the compiler's wasm frames; see `guarded` below.
+ */
+function setupCompile(hypJson, core, onEscapedException = () => { }) {
+    const guard = (method) => guarded(method, hypJson, onEscapedException);
     return {
-        compileJson: bindCompileJson(hypJson),
-        compileJsonCallback: bindCompileJsonCallback(hypJson, core),
-        compileJsonMulti: bindCompileJsonMulti(hypJson),
-        compileStandard: bindCompileStandard(hypJson, core)
+        compileJson: bindCompileJson(hypJson, guard),
+        compileJsonCallback: bindCompileJsonCallback(hypJson, core, guard),
+        compileJsonMulti: bindCompileJsonMulti(hypJson, guard),
+        compileStandard: bindCompileStandard(hypJson, core, guard)
+    };
+}
+/**
+ * Wraps a bound compiler method so that an exception which unwinds through the compiler's wasm
+ * frames is reported before it propagates.
+ *
+ * The compiler is built with Emscripten's JavaScript exception handling: a C++ throw is a
+ * JavaScript throw of a number, which the `invoke_*` trampolines catch at every C++ try block so
+ * that landing pads (destructors, catch clauses) run. Any other JavaScript exception, such as the
+ * RangeError V8 raises when deeply recursive compiler code runs out of stack, or an exception
+ * thrown by an import callback, is rethrown by those trampolines without running the landing
+ * pads. The compiler's globals then stay as they were mid-compilation (the CompilerStack
+ * singleton guard is still taken, TypeProvider is not reset), and every later compilation on this
+ * module instance fails with "You shall not have another CompilerStack aside me." The wrapper
+ * (wrapper.ts) loads a fresh instance of the module in that case, or asks the compiler to discard
+ * the abandoned compilation where it cannot.
+ *
+ * Emscripten also restores the wasm stack pointer at every C++ try block such an exception passes,
+ * but not at the entry point, so the pointer is left below where the call started with nothing but
+ * dead frames above it. It is put back where it was, when the build exposes stackSave/stackRestore.
+ */
+function guarded(method, hypJson, onEscapedException) {
+    if ((0, helpers_1.isNil)(method))
+        return method;
+    return function (...args) {
+        const stackPointer = typeof hypJson.stackSave === 'function' ? hypJson.stackSave() : undefined;
+        try {
+            return method(...args);
+        }
+        catch (e) {
+            if (stackPointer !== undefined && typeof hypJson.stackRestore === 'function') {
+                try {
+                    hypJson.stackRestore(stackPointer);
+                }
+                catch (restoreError) {
+                    // Then the instance is beyond help; the wrapper will not go on with it.
+                }
+            }
+            onEscapedException(e);
+            throw e;
+        }
     };
 }
-exports.setupCompile = setupCompile;
 /**********************
  * COMPILE
  **********************/
@@ -24,18 +71,20 @@ exports.setupCompile = setupCompile;
  * input (text), optimize (bool) -> output (jsontext)
  *
  * @param hypJson The Emscripten compiled Hyperion object.
+ * @param guard See `guarded`.
  */
-function bindCompileJson(hypJson) {
-    return (0, helpers_2.bindHypcMethod)(hypJson, 'compileJSON', 'string', ['string', 'number'], null);
+function bindCompileJson(hypJson, guard) {
+    return guard((0, helpers_2.bindHypcMethod)(hypJson, 'compileJSON', 'string', ['string', 'number'], null));
 }
 /**
  * Returns a binding to the hyperion compileJSONMulti method.
  * input (jsontext), optimize (bool) -> output (jsontext)
  *
  * @param hypJson The Emscripten compiled Hyperion object.
+ * @param guard See `guarded`.
  */
-function bindCompileJsonMulti(hypJson) {
-    return (0, helpers_2.bindHypcMethod)(hypJson, 'compileJSONMulti', 'string', ['string', 'number'], null);
+function bindCompileJsonMulti(hypJson, guard) {
+    return guard((0, helpers_2.bindHypcMethod)(hypJson, 'compileJSONMulti', 'string', ['string', 'number'], null));
 }
 /**
  * Returns a binding to the hyperion compileJSONCallback method.
@@ -43,13 +92,14 @@ function bindCompileJsonMulti(hypJson) {
  *
  * @param hypJson The Emscripten compiled Hyperion object.
  * @param coreBindings The core bound Hyperion methods.
+ * @param guard See `guarded`.
  */
-function bindCompileJsonCallback(hypJson, coreBindings) {
-    const compileInternal = (0, helpers_2.bindHypcMethod)(hypJson, 'compileJSONCallback', 'string', ['string', 'number', 'number'], null);
+function bindCompileJsonCallback(hypJson, coreBindings, guard) {
+    const compileInternal = guard((0, helpers_2.bindHypcMethod)(hypJson, 'compileJSONCallback', 'string', ['string', 'number', 'number'], null));
     if ((0, helpers_1.isNil)(compileInternal))
         return null;
     return function (input, optimize, readCallback) {
-        return runWithCallbacks(hypJson, coreBindings, readCallback, compileInternal, [input, optimize]);
+        return runWithCallbacks(hypJson, coreBindings, readCallback, compileInternal, () => [input, optimize]);
     };
 }
 /**
@@ -59,22 +109,35 @@ function bindCompileJsonCallback(hypJson, coreBindings) {
  *
  * @param hypJson The Emscripten compiled Hyperion object.
  * @param coreBindings The core bound Hyperion methods.
+ * @param guard See `guarded`.
  */
-function bindCompileStandard(hypJson, coreBindings) {
+function bindCompileStandard(hypJson, coreBindings, guard) {
     let boundFunctionStandard = null;
     let boundFunctionHyperion = null;
     // input (jsontext), callback (ptr) -> output (jsontext)
-    const compileInternal = (0, helpers_2.bindHypcMethod)(hypJson, 'compileStandard', 'string', ['string', 'number'], null);
-    // input (jsontext), callback (ptr), callback_context (ptr) -> output (jsontext)
-    boundFunctionHyperion = (0, helpers_2.bindHypcMethod)(hypJson, 'hyperion_compile', 'string', ['string', 'number', 'number'], null);
+    const compileInternal = guard((0, helpers_2.bindHypcMethod)(hypJson, 'compileStandard', 'string', ['string', 'number'], null));
+    // input (ptr to text), callback (ptr), callback_context (ptr) -> output (jsontext)
+    //
+    // The input is passed as a pointer to a copy made with hyperion_alloc(), not as a 'string'
+    // argument: Emscripten's ccall copies a 'string' argument onto the wasm stack, whose size is
+    // fixed when the compiler is built (5 MB), so an input of more than about 1.3 million
+    // characters overflows it and the compilation crashes instead of running. The copy is freed by
+    // the reset() that runWithCallbacks makes after each compilation, like every other allocation
+    // made for the compiler. The output stays a 'string': it is read from the compiler's memory and
+    // freed by the same reset().
+    boundFunctionHyperion = guard((0, helpers_2.bindHypcMethod)(hypJson, 'hyperion_compile', 'string', ['number', 'number', 'number'], null));
     if (!(0, helpers_1.isNil)(compileInternal)) {
         boundFunctionStandard = function (input, readCallback) {
-            return runWithCallbacks(hypJson, coreBindings, readCallback, compileInternal, [input]);
+            return runWithCallbacks(hypJson, coreBindings, readCallback, compileInternal, () => [input]);
         };
     }
     if (!(0, helpers_1.isNil)(boundFunctionHyperion)) {
         boundFunctionStandard = function (input, callbacks) {
-            return runWithCallbacks(hypJson, coreBindings, callbacks, boundFunctionHyperion, [input]);
+            // The copy is made right before the guarded call, once the callback is set up, so that
+            // nothing that can fail runs between the copy and the compilation whose reset() frees it.
+            // It is still outside the guarded call: a failed allocation leaves nothing behind in the
+            // compiler, so it must not mark the instance poisoned.
+            return runWithCallbacks(hypJson, coreBindings, callbacks, boundFunctionHyperion, () => [coreBindings.allocCString(input)]);
         };
     }
     return boundFunctionStandard;
@@ -87,17 +150,83 @@ function wrapCallbackWithKind(coreBindings, callback) {
     return function (context, kind, data, contents, error) {
         // Must be a null pointer.
         (0, assert_1.default)(context === 0, 'Callback context must be null.');
-        const result = callback(coreBindings.copyFromCString(kind), coreBindings.copyFromCString(data));
-        if (typeof result.contents === 'string') {
-            coreBindings.copyToCString(result.contents, contents);
+        // The compiler calls this from inside its wasm frames. An exception thrown here would unwind
+        // through them without running the compiler's cleanup and leave the module instance unusable
+        // (see `guarded`), so a callback that throws, or returns no usable object, is answered with an
+        // error instead, which the compiler reports like any other failed import or query.
+        let contentsString;
+        let errorString;
+        try {
+            const result = callback(coreBindings.copyFromCString(kind), coreBindings.copyFromCString(data));
+            ({ contents: contentsString, error: errorString } = callbackResultStrings(result));
         }
-        if (typeof result.error === 'string') {
-            coreBindings.copyToCString(result.error, error);
+        catch (e) {
+            contentsString = undefined;
+            errorString = `Callback threw ${(0, helpers_1.describeException)(e)}`;
+        }
+        if (contentsString !== undefined) {
+            coreBindings.copyToCString(contentsString, contents);
+        }
+        if (errorString !== undefined) {
+            coreBindings.copyToCString(errorString, error);
         }
     };
 }
-// calls compile() with args || cb
-function runWithCallbacks(hypJson, coreBindings, callbacks, compile, args) {
+/**
+ * The strings to hand the compiler for what a callback returned: its `contents` and `error` where
+ * they are strings, otherwise an error that says what was returned. The compiler must get one of
+ * the two for every result: with neither, it reports "Callback not supported.", which hides that
+ * a callback was there and answered badly. An `error` that is not a string, such as an Error
+ * object, is reported as the error it describes.
+ *
+ * @param result What the callback returned.
+ */
+function callbackResultStrings(result) {
+    if ((0, helpers_1.isNil)(result) || !(0, helpers_1.isObject)(result)) {
+        return { error: `Callback returned ${describeValue(result)} instead of an object with contents or error.` };
+    }
+    const strings = {};
+    if (typeof result.contents === 'string') {
+        strings.contents = result.contents;
+    }
+    if (typeof result.error === 'string') {
+        strings.error = result.error;
+    }
+    else if (!(0, helpers_1.isNil)(result.error)) {
+        strings.error = (0, helpers_1.describeException)(result.error);
+    }
+    if (strings.contents === undefined && strings.error === undefined) {
+        strings.error = (0, helpers_1.isNil)(result.contents)
+            ? 'Callback returned an object with neither contents nor error.'
+            : `Callback returned ${describeValue(result.contents)} as contents instead of a string.`;
+    }
+    return strings;
+}
+/**
+ * Names the kind of a value for an error message: `null`, `undefined`, `an array`, `a string`...
+ *
+ * @param value
+ */
+function describeValue(value) {
+    if ((0, helpers_1.isNil)(value))
+        return String(value);
+    if (Array.isArray(value))
+        return 'an array';
+    return `${typeof value === 'object' ? 'an' : 'a'} ${typeof value}`;
+}
+/**
+ * Runs a compile method with the given callbacks installed, and frees what the compilation
+ * allocated afterwards.
+ *
+ * @param hypJson The Emscripten compiled Hyperion object.
+ * @param coreBindings The core bound Hyperion methods.
+ * @param callbacks The callbacks object (or, before 0.6.0, the import callback) given by the caller.
+ * @param compile The guarded compile method.
+ * @param prepareArgs Returns the arguments that precede the callback and its context. It runs once
+ *   the callback is installed, right before the call, so that an argument allocated in the
+ *   compiler for the call cannot be left behind by a failure to install the callback.
+ */
+function runWithCallbacks(hypJson, coreBindings, callbacks, compile, prepareArgs) {
     if (callbacks) {
         (0, assert_1.default)(typeof callbacks === 'object', 'Invalid callback object specified.');
     }
@@ -137,10 +266,8 @@ function runWithCallbacks(hypJson, coreBindings, callbacks, compile, args) {
     const cb = coreBindings.addFunction(singleCallback, 'viiiii');
     let output;
     try {
-        args.push(cb);
-        // Callback context.
-        args.push(null);
-        output = compile(...args);
+        // The callback, then its context.
+        output = compile(...prepareArgs(), cb, null);
     }
     finally {
         coreBindings.removeFunction(cb);

package/bindings/core.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setupCore = void 0;
+exports.setupCore = setupCore;
 const helpers_1 = require("./helpers");
 const translate_1 = __importDefault(require("../translate"));
 const helpers_2 = require("../common/helpers");
@@ -19,6 +19,7 @@ function setupCore(hypJson) {
         removeFunction: unboundRemoveFunction.bind(this, hypJson),
         copyFromCString: unboundCopyFromCString.bind(this, hypJson),
         copyToCString: unboundCopyToCString.bind(this, hypJson, core.alloc),
+        allocCString: unboundAllocCString.bind(this, hypJson, core.alloc),
         // @ts-ignore
         versionToSemver: versionToSemver(core.version())
     };
@@ -27,7 +28,6 @@ function setupCore(hypJson) {
         ...helpers
     };
 }
-exports.setupCore = setupCore;
 /**********************
  * Core Functions
  **********************/
@@ -81,7 +81,7 @@ function bindReset(hypJson) {
 /**
  * Copy to a C string.
  *
- * Allocates memory using hypc's allocator.
+ * Allocates memory using hypc's allocator and returns the address of the copy.
  *
  * After 0.6.0:
  *   The duty is on hypc-js to free these pointers. We accomplish that by calling `reset` at the end.
@@ -89,13 +89,29 @@ function bindReset(hypJson) {
  * @param hypJson The Emscripten compiled Hyperion object.
  * @param alloc The memory allocation function.
  * @param str The source string being copied to a C string.
- * @param ptr The pointer location where the C string will be set.
  */
-function unboundCopyToCString(hypJson, alloc, str, ptr) {
+function unboundAllocCString(hypJson, alloc, str) {
     const length = hypJson.lengthBytesUTF8(str);
     const buffer = alloc(length + 1);
+    if (!buffer) {
+        // Writing through a NULL pointer would overwrite wasm memory at address 0.
+        throw new Error(`hyperion_alloc failed to allocate ${length + 1} bytes.`);
+    }
     hypJson.stringToUTF8(str, buffer, length + 1);
-    hypJson.setValue(ptr, buffer, '*');
+    return buffer;
+}
+/**
+ * Copy to a C string, and store its address through a pointer.
+ *
+ * Allocates memory as `unboundAllocCString` does.
+ *
+ * @param hypJson The Emscripten compiled Hyperion object.
+ * @param alloc The memory allocation function.
+ * @param str The source string being copied to a C string.
+ * @param ptr The pointer location where the C string will be set.
+ */
+function unboundCopyToCString(hypJson, alloc, str, ptr) {
+    hypJson.setValue(ptr, unboundAllocCString(hypJson, alloc, str), '*');
 }
 /**
  * Wrapper over Emscripten's C String copying function (which can be different

package/bindings/helpers.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSupportedMethods = exports.bindHypcMethodWithFallbackFunc = exports.bindHypcMethod = void 0;
+exports.bindHypcMethod = bindHypcMethod;
+exports.bindHypcMethodWithFallbackFunc = bindHypcMethodWithFallbackFunc;
+exports.getSupportedMethods = getSupportedMethods;
 const helpers_1 = require("../common/helpers");
 function bindHypcMethod(hypJson, method, returnType, args, defaultValue) {
     if ((0, helpers_1.isNil)(hypJson[`_${method}`]) && defaultValue !== undefined) {
@@ -8,7 +10,6 @@ function bindHypcMethod(hypJson, method, returnType, args, defaultValue) {
     }
     return hypJson.cwrap(method, returnType, args);
 }
-exports.bindHypcMethod = bindHypcMethod;
 function bindHypcMethodWithFallbackFunc(hypJson, method, returnType, args, fallbackMethod, finalFallback = undefined) {
     const methodFunc = bindHypcMethod(hypJson, method, returnType, args, null);
     if (!(0, helpers_1.isNil)(methodFunc)) {
@@ -16,7 +17,6 @@ function bindHypcMethodWithFallbackFunc(hypJson, method, returnType, args, fallb
     }
     return bindHypcMethod(hypJson, fallbackMethod, returnType, args, finalFallback);
 }
-exports.bindHypcMethodWithFallbackFunc = bindHypcMethodWithFallbackFunc;
 function getSupportedMethods(hypJson) {
     return {
         licenseSupported: anyMethodExists(hypJson, 'hyperion_license'),
@@ -29,7 +29,6 @@ function getSupportedMethods(hypJson) {
         compileJsonStandardSupported: anyMethodExists(hypJson, 'compileStandard', 'hyperion_compile')
     };
 }
-exports.getSupportedMethods = getSupportedMethods;
 function anyMethodExists(hypJson, ...names) {
     return names.some(name => !(0, helpers_1.isNil)(hypJson[`_${name}`]));
 }

package/bindings/index.js

@@ -1,16 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = setupBindings;
 const core_1 = require("./core");
 const helpers_1 = require("./helpers");
 const compile_1 = require("./compile");
 function setupBindings(hypJson) {
     const coreBindings = (0, core_1.setupCore)(hypJson);
-    const compileBindings = (0, compile_1.setupCompile)(hypJson, coreBindings);
-    const methodFlags = (0, helpers_1.getSupportedMethods)(hypJson);
-    return {
-        methodFlags,
+    const bindings = {
+        methodFlags: (0, helpers_1.getSupportedMethods)(hypJson),
         coreBindings,
-        compileBindings
+        compileBindings: null,
+        // Set, with the exception, once a JavaScript exception has unwound through the compiler's wasm
+        // frames. This module instance cannot compile after that; see `guarded` in ./compile.ts.
+        poisoned: false,
+        poisonedBy: undefined
     };
+    bindings.compileBindings = (0, compile_1.setupCompile)(hypJson, coreBindings, (e) => {
+        bindings.poisoned = true;
+        bindings.poisonedBy = e;
+    });
+    return bindings;
 }
-exports.default = setupBindings;

package/common/helpers.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isObject = exports.isNil = void 0;
+exports.isNil = isNil;
+exports.isObject = isObject;
+exports.describeException = describeException;
 /**
  * Returns true if and only if the value is null or undefined.
  *
@@ -10,7 +12,6 @@ function isNil(value) {
     // Uses == over === which compares both null and undefined.
     return value == null;
 }
-exports.isNil = isNil;
 /**
  * Returns true if and only if the value is an object and not an array.
  *
@@ -21,4 +22,17 @@ function isObject(value) {
     // to confirm it's just an object.
     return typeof value === 'object' && !Array.isArray(value);
 }
-exports.isObject = isObject;
+/**
+ * Returns the exception as a string for an error message, such as `Error: boom` or
+ * `RangeError: Maximum call stack size exceeded`.
+ *
+ * @param e The thrown value.
+ */
+function describeException(e) {
+    try {
+        return String(e);
+    }
+    catch (conversionError) {
+        return 'an exception that cannot be converted to a string';
+    }
+}