convex-rust 0.0.0-stage → 0.1.0

package/dist/cli/scaffold.js

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+import { RUST_TARGET } from "./toolchain.js";
+import { RUST_API_STUB } from "./rustApi.js";
+import { managedConfigToml, resolveConvexFnPath } from "./shim.js";
+/**
+ * Stable Rust is enough for the guest crate (verified with stable 1.99.1: build, run and HTTP action on a
+ * stock backend); nothing in convex_fn or the macros needs nightly features. Override with CONVEX_RUST_CHANNEL.
+ */
+export const DEFAULT_RUST_CHANNEL = "stable";
+/** Cargo target directory kept outside the Convex functions directory (relative to the crate). */
+export function defaultTargetDir(projectRoot, crateDir) {
+    const rel = path.relative(path.resolve(crateDir), path.join(path.resolve(projectRoot), ".convex-rust", "target"));
+    return rel.split(path.sep).join("/");
+}
+function convexFnDependency(rustDir, convexFnPath) {
+    if (convexFnPath) {
+        let p = path.resolve(convexFnPath);
+        const rel = path.relative(path.resolve(rustDir), p);
+        if (!path.isAbsolute(rel))
+            p = rel;
+        return `convex_fn = { path = ${JSON.stringify(p.split(path.sep).join("/"))} }`;
+    }
+    return [
+        "# TODO: `convex_fn` is not published yet and was not found in node_modules/convex-rust/rust.",
+        "# Set CONVEX_FN_PATH (or pass --convex-fn-path) when running `convex-rust init`, or point this at",
+        "# a path/git dependency.",
+        'convex_fn = "0.1"',
+    ].join("\n");
+}
+export function scaffoldFiles(rustDir, opts = {}) {
+    const channel = opts.channel ?? DEFAULT_RUST_CHANNEL;
+    return {
+        "Cargo.toml": `[package]
+name = "convex_rust"
+edition = "2021"
+version = "0.1.0"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+${convexFnDependency(rustDir, opts.convexFnPath ?? resolveConvexFnPath(rustDir))}
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# One wasm per module (smaller cold load on Convex cloud): gate each module with a cargo feature named
+# m-<module> and convex-rust build builds one wasm per module. Heavy dependencies go behind it:
+#   [features]
+#   default = ["m-example", "m-images"]   # default = all, so cargo check sees everything
+#   m-example = []
+#   m-images = ["dep:image"]              # with image = { version = "0.25", optional = true }
+# and in src/lib.rs:  #[cfg(feature = "m-images")] pub mod images;
+# See docs/rust/cloud.md.
+
+# Keeps this crate standalone even when the project root is a Cargo workspace.
+[workspace]
+`,
+        "src/lib.rs": `// Each module in this crate becomes a Convex module under \`rust/\`:
+// \`src/example.rs\` is called as \`api.rust.example.greet\`.
+pub mod example;
+
+// Typed references to your Convex functions, generated by \`convex-rust build\` / \`convex-rust codegen\`.
+#[path = "_generated/api.rs"]
+pub mod api;
+`,
+        "src/_generated/api.rs": RUST_API_STUB,
+        "src/example.rs": `use convex_fn::{action, ConvexArgs, ConvexValue, Ctx, Result};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, ConvexArgs)]
+pub struct GreetArgs {
+    pub name: String,
+}
+
+#[derive(Serialize, ConvexValue)]
+pub struct Greeting {
+    pub text: String,
+}
+
+/// An example action. Call it as \`api.rust.example.greet({ name: "you" })\`.
+/// \`ctx.run_query("module:name", args)\` calls your TypeScript functions.
+#[action]
+pub async fn greet(_ctx: &Ctx, args: GreetArgs) -> Result<Greeting> {
+    Ok(Greeting { text: format!("Hello, {}!", args.name) })
+}
+`,
+        "rust-toolchain.toml": `[toolchain]
+channel = ${JSON.stringify(channel)}
+targets = ["${RUST_TARGET}"]
+components = ["rustfmt", "clippy"]
+`,
+        ".cargo/config.toml": managedConfigToml({ targetDir: opts.targetDir }),
+        // Build outputs. The generated wrappers (*.ts) are small and fine to commit; the wasm is rebuilt by
+        // \`convex-rust build\`, so CI must run that before \`convex deploy\`.
+        ".gitignore": "# cargo output (only used when target-dir in .cargo/config.toml is removed)\ntarget/\n# compiled wasm, regenerated by `convex-rust build`\n_wasm/\n",
+    };
+}
+/** Writes the scaffold; never overwrites existing files. */
+export function scaffoldRust(rustDir, opts = {}) {
+    const result = { created: [], skipped: [] };
+    for (const [rel, contents] of Object.entries(scaffoldFiles(rustDir, opts))) {
+        const full = path.join(rustDir, rel);
+        if (fs.existsSync(full)) {
+            result.skipped.push(rel);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, contents);
+        result.created.push(rel);
+    }
+    return result;
+}

package/dist/cli/shim.d.ts

@@ -0,0 +1,30 @@
+export declare const MANAGED_BEGIN = "# >>> convex-managed:patch (begin)";
+export declare const MANAGED_END = "# <<< convex-managed:patch (end)";
+/**
+ * Where the reqwest shim lives: `CONVEX_REQWEST_PATH`, else `node_modules/convex-rust/rust/convex_reqwest`
+ * (or the fork's `node_modules/convex/rust/convex_reqwest`) above the crate, else this package's own copy.
+ */
+export declare function resolveReqwestShimPath(rustDir?: string, env?: Record<string, string | undefined>): string | undefined;
+/** Where the `convex_fn` crate lives (`CONVEX_FN_PATH`, else shipped copy), if anywhere. */
+export declare function resolveConvexFnPath(rustDir?: string, env?: Record<string, string | undefined>): string | undefined;
+/** Portable when inside node_modules (relative), absolute otherwise. */
+export declare function displayPath(rustDir: string, p: string): string;
+export declare function patchBlockBody(shimPath?: string, convexFnPath?: string, withReqwest?: boolean): string;
+/** Absolute path of the user's `convex_fn` path dependency in `<rustDir>/Cargo.toml`. */
+export declare function userConvexFnPath(rustDir: string): string | undefined;
+export interface ConfigOptions {
+    shimPath?: string | undefined;
+    convexFnPath?: string | undefined;
+    withReqwest?: boolean;
+    /** `[build] target-dir`, relative to the crate directory (the parent of `.cargo`). */
+    targetDir?: string | undefined;
+}
+export declare function managedConfigToml(o?: ConfigOptions): string;
+/** Does the crate depend on reqwest (directly or transitively)? */
+export declare function usesReqwest(rustDir: string): boolean;
+/**
+ * Rewrites the managed block of `<rustDir>/.cargo/config.toml`; everything outside the
+ * markers is left alone. Creates the file when missing (and `Cargo.toml` exists); a file
+ * without markers is left alone. Returns true if the file changed.
+ */
+export declare function syncManagedPatch(rustDir: string, shimPath?: string | undefined, withReqwest?: boolean): boolean;

package/dist/cli/shim.js

@@ -0,0 +1,140 @@
+// Managed `.cargo/config.toml` patch block: swaps `reqwest` for the built-in shim
+// (crates/convex_reqwest), which sends requests through the host fetch. Port of the fork
+// CLI's lib/rust/scaffold.ts.
+import fs from "node:fs";
+import path from "node:path";
+export const MANAGED_BEGIN = "# >>> convex-managed:patch (begin)";
+export const MANAGED_END = "# <<< convex-managed:patch (end)";
+const toToml = (x) => JSON.stringify(x.split(path.sep).join("/"));
+/** `node_modules/<pkg>/rust/<crate>` found by walking up from `fromDir`. */
+function findInNodeModules(fromDir, pkg, crate) {
+    let dir = path.resolve(fromDir);
+    for (;;) {
+        const p = path.join(dir, "node_modules", pkg, "rust", crate);
+        if (fs.existsSync(path.join(p, "Cargo.toml")))
+            return p;
+        const up = path.dirname(dir);
+        if (up === dir)
+            return undefined;
+        dir = up;
+    }
+}
+/** The package's own copy (`<package>/rust/<crate>`, created by `npm run vendor-crates`). */
+function ownCopy(crate) {
+    const here = path.dirname(new URL(import.meta.url).pathname);
+    const p = path.resolve(here, "..", "..", "rust", crate);
+    return fs.existsSync(path.join(p, "Cargo.toml")) ? p : undefined;
+}
+/**
+ * Where the reqwest shim lives: `CONVEX_REQWEST_PATH`, else `node_modules/convex-rust/rust/convex_reqwest`
+ * (or the fork's `node_modules/convex/rust/convex_reqwest`) above the crate, else this package's own copy.
+ */
+export function resolveReqwestShimPath(rustDir, env = process.env) {
+    if (env.CONVEX_REQWEST_PATH)
+        return path.resolve(env.CONVEX_REQWEST_PATH);
+    if (rustDir) {
+        for (const pkg of ["convex-rust", "convex"]) {
+            const p = findInNodeModules(rustDir, pkg, "convex_reqwest");
+            if (p)
+                return p;
+        }
+    }
+    return ownCopy("convex_reqwest");
+}
+/** Where the `convex_fn` crate lives (`CONVEX_FN_PATH`, else shipped copy), if anywhere. */
+export function resolveConvexFnPath(rustDir, env = process.env) {
+    if (env.CONVEX_FN_PATH)
+        return path.resolve(env.CONVEX_FN_PATH);
+    if (rustDir) {
+        for (const pkg of ["convex-rust", "convex"]) {
+            const p = findInNodeModules(rustDir, pkg, "convex_fn");
+            if (p)
+                return p;
+        }
+    }
+    return ownCopy("convex_fn");
+}
+/** Portable when inside node_modules (relative), absolute otherwise. */
+export function displayPath(rustDir, p) {
+    if (!p.split(path.sep).includes("node_modules"))
+        return p;
+    const rel = path.relative(path.resolve(rustDir), p);
+    return path.isAbsolute(rel) ? p : rel;
+}
+export function patchBlockBody(shimPath, convexFnPath, withReqwest = true) {
+    if (!withReqwest) {
+        return "# Nothing to patch: no dependency uses reqwest. When one is added (cargo add reqwest),\n# the next `convex-rust build` fills in the built-in reqwest replacement here.\n";
+    }
+    if (!shimPath) {
+        return "# The built-in reqwest shim was not found (set CONVEX_REQWEST_PATH);\n# crates that depend on reqwest will not be able to make requests.\n";
+    }
+    // The shim depends on the registry `convex_fn`; with a path dependency, patch the
+    // registry one to the same path so both resolve to one crate.
+    const fnPatch = convexFnPath ? `convex_fn = { path = ${toToml(convexFnPath)} }\n` : "";
+    return `[patch.crates-io]\nreqwest = { path = ${toToml(shimPath)} }\n${fnPatch}`;
+}
+/** Absolute path of the user's `convex_fn` path dependency in `<rustDir>/Cargo.toml`. */
+export function userConvexFnPath(rustDir) {
+    let toml;
+    try {
+        toml = fs.readFileSync(path.join(rustDir, "Cargo.toml"), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const m = /^convex_fn\s*=\s*\{[^}\n]*\bpath\s*=\s*"([^"]+)"/m.exec(toml);
+    return m ? path.resolve(rustDir, m[1]) : undefined;
+}
+export function managedConfigToml(o = {}) {
+    const build = o.targetDir
+        ? `# Keeps cargo's output (target/) out of the Convex functions directory, whose bundler\n# would otherwise walk it.\n[build]\ntarget-dir = ${toToml(o.targetDir)}\n\n`
+        : "";
+    // No `[build] target`: plain `cargo test` / `cargo check` run on the host; convex-rust passes --target.
+    return `# Managed by \`convex-rust\`: edit with care, the block below is regenerated.\n${build}${MANAGED_BEGIN}\n${patchBlockBody(o.shimPath, o.convexFnPath, o.withReqwest ?? false)}${MANAGED_END}\n`;
+}
+/** Does the crate depend on reqwest (directly or transitively)? */
+export function usesReqwest(rustDir) {
+    const read = (f) => {
+        try {
+            return fs.readFileSync(path.join(rustDir, f), "utf8");
+        }
+        catch {
+            return "";
+        }
+    };
+    if (/^\[\[package\]\]\s*\nname\s*=\s*"reqwest"\s*$/m.test(read("Cargo.lock")))
+        return true;
+    const toml = read("Cargo.toml");
+    return /^\s*reqwest\s*=/m.test(toml) || /^\s*\[[^\]]*\bdependencies\.reqwest\]/m.test(toml);
+}
+/**
+ * Rewrites the managed block of `<rustDir>/.cargo/config.toml`; everything outside the
+ * markers is left alone. Creates the file when missing (and `Cargo.toml` exists); a file
+ * without markers is left alone. Returns true if the file changed.
+ */
+export function syncManagedPatch(rustDir, shimPath = resolveReqwestShimPath(rustDir), withReqwest = usesReqwest(rustDir)) {
+    const shim = shimPath ? displayPath(rustDir, shimPath) : undefined;
+    const rawFn = shim ? userConvexFnPath(rustDir) : undefined;
+    const fnPath = rawFn ? displayPath(rustDir, rawFn) : undefined;
+    const file = path.join(rustDir, ".cargo", "config.toml");
+    let cur;
+    try {
+        cur = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        if (!fs.existsSync(path.join(rustDir, "Cargo.toml")))
+            return false;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, managedConfigToml({ shimPath: shim, convexFnPath: fnPath, withReqwest }));
+        return true;
+    }
+    const b = cur.indexOf(MANAGED_BEGIN);
+    const e = cur.indexOf(MANAGED_END);
+    if (b < 0 || e < b)
+        return false;
+    const next = cur.slice(0, b) + MANAGED_BEGIN + "\n" + patchBlockBody(shim, fnPath, withReqwest) + cur.slice(e);
+    if (next === cur)
+        return false;
+    fs.writeFileSync(file, next);
+    return true;
+}

package/dist/cli/size.d.ts

@@ -0,0 +1,17 @@
+/** Size of the compiled wasm and its biggest sections. */
+export declare const WASM_SIZE_WARN_BYTES: number;
+export interface WasmSizes {
+    total: number;
+    code: number;
+    data: number;
+    names: number;
+    other: number;
+}
+export declare function readLeb(bytes: Uint8Array, pos: number): [number, number];
+/** Section sizes (payload bytes) from the binary format; no instantiation. */
+export declare function wasmSectionSizes(wasm: Uint8Array): WasmSizes;
+export declare function formatBytes(n: number): string;
+export declare function describeWasmSize(wasm: Uint8Array, warnBytes?: number): {
+    message: string;
+    warning?: string;
+};

package/dist/cli/size.js

@@ -0,0 +1,73 @@
+/** Size of the compiled wasm and its biggest sections. */
+export const WASM_SIZE_WARN_BYTES = 20 * 1024 * 1024;
+export function readLeb(bytes, pos) {
+    let result = 0;
+    let shift = 0;
+    while (pos < bytes.length) {
+        const b = bytes[pos++];
+        result += (b & 0x7f) * 2 ** shift;
+        if ((b & 0x80) === 0)
+            return [result, pos];
+        shift += 7;
+    }
+    return [result, pos]; // truncated input
+}
+/** Section sizes (payload bytes) from the binary format; no instantiation. */
+export function wasmSectionSizes(wasm) {
+    const sizes = {
+        total: wasm.length,
+        code: 0,
+        data: 0,
+        names: 0,
+        other: 0,
+    };
+    let pos = 8;
+    const decoder = new TextDecoder();
+    while (pos < wasm.length) {
+        const id = wasm[pos++];
+        let size;
+        [size, pos] = readLeb(wasm, pos);
+        const end = pos + size;
+        if (id === 10)
+            sizes.code += size;
+        else if (id === 11)
+            sizes.data += size;
+        else if (id === 0) {
+            const [nameLen, namePos] = readLeb(wasm, pos);
+            const name = decoder.decode(wasm.subarray(namePos, namePos + nameLen));
+            if (name === "name")
+                sizes.names += size;
+            else
+                sizes.other += size;
+        }
+        else
+            sizes.other += size;
+        pos = end;
+    }
+    return sizes;
+}
+export function formatBytes(n) {
+    if (n >= 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    if (n >= 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${n} B`;
+}
+export function describeWasmSize(wasm, warnBytes = WASM_SIZE_WARN_BYTES) {
+    const s = wasmSectionSizes(wasm);
+    const message = `Rust wasm: ${formatBytes(s.total)} ` +
+        `(code ${formatBytes(s.code)}, data ${formatBytes(s.data)}, ` +
+        `names ${formatBytes(s.names)}, other ${formatBytes(s.other)})`;
+    // Measured on the Convex cloud: the platform re-evaluates the module (and compiles its wasm) on every call.
+    const perCall = s.total >= 1024 * 1024
+        ? `Loading it costs about ${Math.round((s.total / 1024 / 1024) * 0.9)} ms on every call (cloud); gate modules with m-<module> cargo features to ship one smaller wasm per module (docs/rust/cloud.md).`
+        : undefined;
+    if (s.total <= warnBytes)
+        return { message: perCall ? `${message}\n${perCall}` : message };
+    return {
+        message: perCall ? `${message}\n${perCall}` : message,
+        warning: `The Rust wasm is ${formatBytes(s.total)}, above the ${formatBytes(warnBytes)} threshold. ` +
+            `Largest section: ${s.code >= s.data ? "code" : "data"}. ` +
+            `Consider fewer/lighter dependencies, \`opt-level = "z"\`, \`lto = true\`, or installing \`wasm-opt\` (binaryen).`,
+    };
+}

package/dist/cli/split.d.ts

@@ -0,0 +1,20 @@
+/** Rewrites the export section, keeping only the exports for which `keep(name)` is true. */
+export declare function filterExports(wasm: Uint8Array, keep: (name: string) => boolean): Uint8Array;
+/**
+ * Whether an export stays in a module's wasm. `prefixes` are `convex_run:<module_path>:`. The match is
+ * exact: what follows the prefix is the function name (no `:`), so `convex_run:c::a::b:f` is not kept in
+ * the wasm of module `c::a`.
+ */
+export declare function keepsExport(exportName: string, prefixes: string[]): boolean;
+export interface SplitOptions {
+    /** wasm-opt flags (same as the whole-module optimization). */
+    wasmOptArgs: string[];
+    cacheDir: string;
+    log?: (m: string) => void;
+}
+/**
+ * One wasm per Convex module name (`cpu`, `a/b`), keyed by that name. `modulePaths` are the Rust
+ * `module_path!()` values of the functions. Returns null when `wasm-opt` is unavailable or fails
+ * (callers fall back to the single shared wasm).
+ */
+export declare function splitWasmByModule(wasm: Uint8Array, modulePaths: string[], opts: SplitOptions): Map<string, Uint8Array> | null;

package/dist/cli/split.js

@@ -0,0 +1,140 @@
+// Per-module wasm: one copy of the module per Convex module, with only that module's `convex_run:*`
+// exports, so wasm-opt can drop the code (and its dependencies) the other modules need. A stock Convex
+// deployment compiles every wasm a module imports on EVERY call (module scope is not kept between calls),
+// at roughly 0.8 ms per MB, so a small module should not pay for the whole crate.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { convexModuleName } from "./manifest.js";
+function readLeb(b, pos) {
+    let r = 0;
+    let shift = 0;
+    while (pos < b.length) {
+        const x = b[pos++];
+        r += (x & 0x7f) * 2 ** shift;
+        if ((x & 0x80) === 0)
+            return [r, pos];
+        shift += 7;
+    }
+    throw new Error("truncated LEB128");
+}
+function lebBytes(n) {
+    const out = [];
+    do {
+        let b = n % 128;
+        n = Math.floor(n / 128);
+        if (n > 0)
+            b |= 0x80;
+        out.push(b);
+    } while (n > 0);
+    return out;
+}
+/** Rewrites the export section, keeping only the exports for which `keep(name)` is true. */
+export function filterExports(wasm, keep) {
+    const dec = new TextDecoder();
+    let pos = 8;
+    while (pos < wasm.length) {
+        const start = pos;
+        const id = wasm[pos++];
+        let size;
+        [size, pos] = readLeb(wasm, pos);
+        const payload = pos;
+        const end = pos + size;
+        if (id === 7) {
+            let count;
+            let p;
+            [count, p] = readLeb(wasm, payload);
+            const kept = [];
+            for (let i = 0; i < count; i++) {
+                const s = p;
+                let len;
+                [len, p] = readLeb(wasm, p);
+                const name = dec.decode(wasm.subarray(p, p + len));
+                p += len + 1; // kind
+                [, p] = readLeb(wasm, p); // index
+                if (keep(name))
+                    kept.push(Array.from(wasm.subarray(s, p)));
+            }
+            const body = [...lebBytes(kept.length), ...kept.flat()];
+            const out = new Uint8Array(start + 1 + lebBytes(body.length).length + body.length + (wasm.length - end));
+            out.set(wasm.subarray(0, start), 0);
+            let o = start;
+            out[o++] = 7;
+            for (const x of lebBytes(body.length))
+                out[o++] = x;
+            out.set(body, o);
+            o += body.length;
+            out.set(wasm.subarray(end), o);
+            return out;
+        }
+        pos = end;
+    }
+    return wasm;
+}
+/**
+ * Whether an export stays in a module's wasm. `prefixes` are `convex_run:<module_path>:`. The match is
+ * exact: what follows the prefix is the function name (no `:`), so `convex_run:c::a::b:f` is not kept in
+ * the wasm of module `c::a`.
+ */
+export function keepsExport(exportName, prefixes) {
+    return (!exportName.startsWith("convex_run:") ||
+        prefixes.some((p) => exportName.startsWith(p) && !exportName.includes(":", p.length)));
+}
+/**
+ * One wasm per Convex module name (`cpu`, `a/b`), keyed by that name. `modulePaths` are the Rust
+ * `module_path!()` values of the functions. Returns null when `wasm-opt` is unavailable or fails
+ * (callers fall back to the single shared wasm).
+ */
+export function splitWasmByModule(wasm, modulePaths, opts) {
+    const log = opts.log ?? (() => { });
+    const ver = spawnSync("wasm-opt", ["--version"], { encoding: "utf8" });
+    if (ver.status !== 0) {
+        log("--split needs wasm-opt (binaryen) on PATH; using one shared wasm");
+        return null;
+    }
+    const modules = new Map();
+    for (const mp of modulePaths) {
+        const m = convexModuleName(mp);
+        if (!modules.has(m))
+            modules.set(m, new Set());
+        modules.get(m).add(mp);
+    }
+    const prefix = (mp) => `convex_run:${mp}:`;
+    const out = new Map();
+    fs.mkdirSync(opts.cacheDir, { recursive: true });
+    for (const [name, mps] of modules) {
+        const prefixes = [...mps].map(prefix);
+        const filtered = filterExports(wasm, (e) => keepsExport(e, prefixes));
+        const key = createHash("sha256")
+            .update(ver.stdout + "\0" + opts.wasmOptArgs.join(" ") + "\0split")
+            .update(filtered)
+            .digest("hex");
+        const cached = path.join(opts.cacheDir, `${key}.wasm`);
+        if (fs.existsSync(cached)) {
+            out.set(name, new Uint8Array(fs.readFileSync(cached)));
+            continue;
+        }
+        const src = path.join(opts.cacheDir, `${key}.${process.pid}.in`);
+        const dst = path.join(opts.cacheDir, `${key}.${process.pid}.tmp`);
+        fs.writeFileSync(src, filtered);
+        try {
+            const r = spawnSync("wasm-opt", [...opts.wasmOptArgs, "--remove-unused-module-elements", src, "-o", dst], {
+                stdio: ["ignore", "ignore", "pipe"],
+                encoding: "utf8",
+            });
+            if (r.status !== 0) {
+                log(`wasm-opt failed splitting ${name} (${r.status}); using one shared wasm`);
+                return null;
+            }
+            const bytes = new Uint8Array(fs.readFileSync(dst));
+            fs.renameSync(dst, cached);
+            out.set(name, bytes);
+        }
+        finally {
+            fs.rmSync(src, { force: true });
+            fs.rmSync(dst, { force: true });
+        }
+    }
+    return out;
+}

package/dist/cli/symbols.d.ts

@@ -0,0 +1,30 @@
+export interface SymbolMap {
+    version: 1;
+    /** File name under `_wasm/`. */
+    wasm: string;
+    /** Convex modules (`cpu`, `a/b`) whose functions this wasm exports. */
+    modules: string[];
+    /** Function index (imports first, as in `wasm-function[N]`) to demangled name. */
+    names: Record<string, string>;
+}
+/** Function names (subsection 1) of the "name" custom section, by function index. */
+export declare function parseNameSection(wasm: Uint8Array): Map<number, string>;
+/** Parses `wasm-opt --print-function-map` output (`index:name` per line). */
+export declare function parseFunctionMap(text: string): Map<number, string>;
+export declare function buildSymbolMap(names: Map<number, string>, info: {
+    wasm: string;
+    modules: string[];
+}): SymbolMap;
+export declare function symbolsDir(targetDir: string): string;
+/** Replaces the maps in `dir` with `maps` (stale ones removed). */
+export declare function writeSymbolMaps(dir: string, maps: SymbolMap[]): string[];
+export declare function readSymbolMaps(dir: string): SymbolMap[];
+/**
+ * Rewrites `wasm-function[N]:0xOFF` into `name (wasm-function[N]:0xOFF)`. With several maps, `module` picks one;
+ * otherwise a module named like `rust/<module>` in the text does, if exactly one does.
+ */
+export declare function symbolize(text: string, maps: SymbolMap[], module?: string): {
+    text: string;
+    replaced: number;
+    note?: string;
+};