cppbolt 0.1.1 → 1.0.0

package/README.md

@@ -2,8 +2,6 @@
 
 cppbolt compiles a subset of C++17 directly to WebAssembly without LLVM, Emscripten, or a native toolchain. This package contains the compiler built for `wasm32-unknown-unknown`; it exposes a C ABI and has no imports, so you can instantiate it with an empty import object in Node.js, browsers, or Web Workers.
 
-The package contains the raw WebAssembly module with no JavaScript wrapper or CLI. You call the exports directly.
-
 ## Installation
 
 ```sh
@@ -12,74 +10,86 @@ npm install cppbolt
 
 ## Usage
 
+### Node.js: compile only
+
+`createCompiler()` returns a compiler. `compile()` turns C++ source into a
+complete WebAssembly module as a `Uint8Array`.
+
 ```js
-import { readFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-
-const require = createRequire(import.meta.url);
-const wasmPath = require.resolve("cppbolt/wasm/cppbolt.wasm");
-const { instance } = await WebAssembly.instantiate(await readFile(wasmPath), {});
-const compiler = instance.exports;
-
-function compile(source) {
-  const input = new TextEncoder().encode(source);
-  const inputPtr = compiler.alloc_buffer(input.length);
-  new Uint8Array(compiler.memory.buffer, inputPtr, input.length).set(input);
-
-  const resultPtr = compiler.compile_wasm(inputPtr, input.length);
-  compiler.dealloc_buffer(inputPtr, input.length);
-
-  if (resultPtr === 0) {
-    const length = compiler.get_error_len();
-    const bytes = new Uint8Array(compiler.memory.buffer, compiler.get_error_ptr(), length);
-    throw new Error(new TextDecoder().decode(bytes));
-  }
-
-  const length = compiler.get_result_len();
-  const output = new Uint8Array(compiler.memory.buffer, resultPtr, length).slice();
-  compiler.free_result(resultPtr, length);
-  return output;
-}
-
-const wasm = compile(`
-  #include <iostream>
-
-  int main() {
-      std::cout << "Hello from WebAssembly C++!" << std::endl;
-      return 0;
-  }
+import { createCompiler } from "cppbolt";
+
+const compiler = await createCompiler();
+
+const wasm = compiler.compile(`
+    #include <iostream>
+    int main() {
+        std::cout << "cppbolt says hello!" << std::endl;
+        return 0;
+    }
 `);
 ```
 
-`wasm` is a complete WebAssembly module.
+### Node.js: compile and run
 
-### Browser
+`compileAndRun()` compiles the source and immediately executes it, returning
+its stdout and exit status.
 
-Serve `cppbolt.wasm` from your site, then load it:
+```js
+import { createCompiler, compileAndRun } from "cppbolt";
+
+const compiler = await createCompiler();
+
+const { stdout, exitCode } = await compileAndRun(
+  compiler,
+  `
+    #include <iostream>
+    int main() {
+        std::cout << "cppbolt says hello!" << std::endl;
+        return 0;
+    }
+`,
+);
+
+console.log(stdout); // "cppbolt says hello!\n"
+console.log(exitCode); // 0
+```
+
+### Browser (CDN `<script>` tag)
 
 ```html
-<script type="module">
-  const response = await fetch("/wasm/cppbolt.wasm");
-  const { instance } = await WebAssembly.instantiateStreaming(response, {});
-  const compiler = instance.exports;
+<script src="https://cdn.jsdelivr.net/npm/cppbolt@1.0.1/dist/cppbolt.browser.js"></script>
+<script>
+  (async () => {
+    const compiler = await CppBolt.createCompiler();
+    const { stdout, exitCode } = await CppBolt.compileAndRun(compiler, `
+      #include <iostream>
+      int main() {
+          std::cout << "cppbolt says hello!" << std::endl;
+          return 0;
+      }
+    `,
+    );
+    console.log(stdout, exitCode);
+  })();
 </script>
 ```
 
-`instantiateStreaming` needs the server to send `Content-Type: application/wasm`; otherwise use `WebAssembly.instantiate(await response.arrayBuffer(), {})`. The compiler ABI interaction inside the `compile` function can be reused in browsers. Replace the Node.js-specific WASM loading code with the browser loading example above.
+`createCompiler()` resolves `wasm/cppbolt.wasm` relative to the script URL. When
+using a bundler, import from `"cppbolt"` instead.
 
 ## Compiler API
 
 Pointers are 32-bit offsets into the module's exported `memory`.
 
-| Export | Signature | Description |
-|---|---|---|
-| `alloc_buffer` | `(size) -> ptr` | Allocates an uninitialized input buffer. |
-| `dealloc_buffer` | `(ptr, size) -> void` | Releases an input buffer with the size passed to `alloc_buffer`. |
-| `compile_wasm` | `(ptr, len) -> ptr` | Compiles UTF-8 source. Returns a pointer to the emitted module, or `0` on error. |
-| `get_result_len` | `() -> len` | Returns the byte length of the result from the most recent `compile_wasm` call, or `0` if that call failed. |
-| `free_result` | `(ptr, len) -> void` | Releases a result buffer returned by `compile_wasm`. |
-| `get_error_ptr` | `() -> ptr` | Returns the address of the static error buffer. |
-| `get_error_len` | `() -> len` | Returns the byte length of the diagnostic from the most recent failed `compile_wasm` call, or `0` if it succeeded. |
+| Export           | Signature             | Description                                                                                                        |
+| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `alloc_buffer`   | `(size) -> ptr`       | Allocates an uninitialized input buffer.                                                                           |
+| `dealloc_buffer` | `(ptr, size) -> void` | Releases an input buffer with the size passed to `alloc_buffer`.                                                   |
+| `compile_wasm`   | `(ptr, len) -> ptr`   | Compiles UTF-8 source. Returns a pointer to the emitted module, or `0` on error.                                   |
+| `get_result_len` | `() -> len`           | Returns the byte length of the result from the most recent `compile_wasm` call, or `0` if that call failed.        |
+| `free_result`    | `(ptr, len) -> void`  | Releases a result buffer returned by `compile_wasm`.                                                               |
+| `get_error_ptr`  | `() -> ptr`           | Returns the address of the static error buffer.                                                                    |
+| `get_error_len`  | `() -> len`           | Returns the byte length of the diagnostic from the most recent failed `compile_wasm` call, or `0` if it succeeded. |
 
 Ownership and lifetime rules:
 
@@ -104,17 +114,29 @@ See the [supported C++ subset](https://ajtimepyro.is-a.dev/cppbolt/book/user/sup
 
 Emitted modules are WebAssembly binaries that import standard I/O functions from an `env` namespace. Every emitted module imports all five functions:
 
-| Import | Signature | Purpose |
-|---|---|---|
-| `env.print_char` | `(i32) -> void` | Write one character byte to stdout. |
-| `env.print_int` | `(i64, i32, i32, i32, i32) -> i32` | Format and write an integer. Returns the character count. |
-| `env.print_double` | `(f64, i32, i32, i32, i32) -> i32` | Format and write a double. Returns the character count. |
-| `env.read_char` | `() -> i32` | Read one character byte from stdin, or `-1` at end of input. |
-| `env.exit` | `(i32) -> void` | Terminate with the given status code. |
+| Import             | Signature                          | Purpose                                                      |
+| ------------------ | ---------------------------------- | ------------------------------------------------------------ |
+| `env.print_char`   | `(i32) -> void`                    | Write one character byte to stdout.                          |
+| `env.print_int`    | `(i64, i32, i32, i32, i32) -> i32` | Format and write an integer. Returns the character count.    |
+| `env.print_double` | `(f64, i32, i32, i32, i32) -> i32` | Format and write a double. Returns the character count.      |
+| `env.read_char`    | `() -> i32`                        | Read one character byte from stdin, or `-1` at end of input. |
+| `env.exit`         | `(i32) -> void`                    | Terminate with the given status code.                        |
 
 Emitted modules export `memory`, `__stack_pointer`, and `__heap_base`, plus `main` if the program defines it. The compiler gives them a 256 MiB maximum linear memory, raised only when static data requires more.
 
-The package does not include a host runtime. The repository's [`web/host.js`](https://github.com/AJTimePyro/cppbolt/blob/main/web/host.js) provides a reference implementation for Node.js and browsers. It handles the integer and floating-point formatting flags.
+### Host runtime API
+
+The package ships a host for those imports, so you do not implement `env.*`
+yourself.
+
+- `createWasmHost(options?) -> WasmHost` builds the import environment. Options
+  are `stdin` (a string, or `() => number` for streaming input), `onStdout(chunk)`,
+  and `onExit(code)`. The result exposes `imports` for `WebAssembly.instantiate`
+  and `getStdout()`.
+- `new CppBoltRunner(host).run(wasmBytes) -> Promise<RunResult>` instantiates a
+  module, calls `main` (or `_start`), and returns `{ stdout, exitCode }`. A
+  WebAssembly trap is reported as exit code 134 instead of throwing.
+- `compileAndRun(compiler, source, options?)` compiles and runs in one call.
 
 ## Notes
 

package/dist/compiler.d.ts

@@ -0,0 +1,16 @@
+export declare class CompileError extends Error {
+    readonly diagnostic: string;
+    constructor(diagnostic: string);
+}
+export declare class CppBoltCompiler {
+    private readonly _exports;
+    constructor(instance: WebAssembly.Instance);
+    compile(source: string): Uint8Array;
+}
+/**
+ * Load cppbolt.wasm and return a CppBoltCompiler.
+ *
+ * In Node.js, resolves wasm/cppbolt.wasm from the package directory.
+ * In a browser <script> tag, fetches it relative to the script's own URL.
+ */
+export declare function createCompiler(): Promise<CppBoltCompiler>;

package/dist/compiler.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CppBoltCompiler = exports.CompileError = void 0;
+exports.createCompiler = createCompiler;
+function tryRequire(id) {
+    if (typeof require !== "function")
+        return null;
+    try {
+        return require(id);
+    }
+    catch {
+        return null;
+    }
+}
+const fs = tryRequire("fs");
+const path = tryRequire("path");
+const scriptSrc = typeof document !== "undefined" &&
+    document.currentScript instanceof HTMLScriptElement
+    ? document.currentScript.src
+    : null;
+function decodeString(memory, ptr, len) {
+    return new TextDecoder().decode(new Uint8Array(memory.buffer, ptr, len));
+}
+class CompileError extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(diagnostic);
+        this.name = "CompileError";
+        this.diagnostic = diagnostic;
+    }
+}
+exports.CompileError = CompileError;
+class CppBoltCompiler {
+    _exports;
+    constructor(instance) {
+        this._exports = instance.exports;
+    }
+    compile(source) {
+        const ex = this._exports;
+        const mem = ex.memory;
+        const srcBytes = new TextEncoder().encode(source);
+        const srcPtr = ex.alloc_buffer(srcBytes.length);
+        new Uint8Array(mem.buffer, srcPtr, srcBytes.length).set(srcBytes);
+        const resultPtr = ex.compile_wasm(srcPtr, srcBytes.length);
+        ex.dealloc_buffer(srcPtr, srcBytes.length);
+        if (resultPtr === 0) {
+            throw new CompileError(decodeString(mem, ex.get_error_ptr(), ex.get_error_len()));
+        }
+        const resultLen = ex.get_result_len();
+        const output = new Uint8Array(mem.buffer, resultPtr, resultLen).slice();
+        ex.free_result(resultPtr, resultLen);
+        return output;
+    }
+}
+exports.CppBoltCompiler = CppBoltCompiler;
+/**
+ * Load cppbolt.wasm and return a CppBoltCompiler.
+ *
+ * In Node.js, resolves wasm/cppbolt.wasm from the package directory.
+ * In a browser <script> tag, fetches it relative to the script's own URL.
+ */
+async function createCompiler() {
+    if (fs && path && typeof __dirname === "string") {
+        const localPath = path.join(__dirname, "..", "wasm", "cppbolt.wasm");
+        if (fs.existsSync(localPath)) {
+            return new CppBoltCompiler(await loadFromBytes(fs.readFileSync(localPath)));
+        }
+    }
+    const wasmUrl = scriptSrc
+        ? new URL("../wasm/cppbolt.wasm", scriptSrc).href
+        : null;
+    if (wasmUrl) {
+        return new CppBoltCompiler(await loadFromResponse(await fetch(wasmUrl)));
+    }
+    throw new Error("cppbolt: could not locate wasm binary. " +
+        "Load this script from a URL (CDN / local server) or use the Node.js package.");
+}
+async function loadFromResponse(response) {
+    if (!response.ok) {
+        throw new Error(`cppbolt: failed to fetch wasm (HTTP ${response.status})`);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/wasm")) {
+        const { instance } = await WebAssembly.instantiateStreaming(response, {});
+        return instance;
+    }
+    return loadFromBytes(await response.arrayBuffer());
+}
+async function loadFromBytes(bytes) {
+    const { instance } = await WebAssembly.instantiate(bytes, {});
+    return instance;
+}