Rust Performance

Rust Performance Guide

Principles for writing performant Rust in verter_compiler.

1. Batch Over Incremental

CodeTransform operations like overwrite() and prepend_left() each walk the chunk list in O(n). Calling them in a loop is O(n*N). Collect operations into Vecs and apply with batch APIs:

• batch_overwrite(ops: &[(u32, u32, &str)]) — sorted overwrites in one chunk-list pass
• batch_prepend_left_static(ops: &[(u32, &str)]) — sorted inserts in one pass

// BAD: O(n) per call × N calls
for (start, end, content) in replacements {
    code_transform.overwrite(start, end, content);
}

// GOOD: O(n+m) single pass
replacements.sort_by_key(|(start, _, _)| *start);
code_transform.batch_overwrite(&replacements);

If calling a mutating method in a loop, ask whether operations can be collected and applied in one traversal.

2. Allocation Hierarchy

Prefer allocations in this order (fastest to slowest):

1. &'static str — zero-cost, compile-time constants
2. &'alloc str via code_transform.alloc_str(buf) — OXC bump allocator, freed in bulk
3. &str from ctx.input[start..end] — zero-cost slice of source
4. Reusable &mut String buffer — amortized cost via capacity reuse
5. String — heap-allocated, avoid in hot paths

3. Reusable Buffer Pattern

Codegen generators (e.g., VdomTemplateGenerator) keep a buf: String field. Use std::mem::take to temporarily take ownership — avoids borrow conflicts with other self fields:

// Take buffer — avoids per-element heap allocation:
let mut buf = std::mem::take(&mut self.buf);
process_element(&mut buf, ...);
self.buf = buf; // return — retains capacity for next element

// In called functions, accept buf: &mut String.
// Use `buf` directly, not `&mut buf` (it's already &mut String).

After building text in buf, persist via bump allocator:

buf.clear();
buf.push_str("_createVNode(");
buf.push_str(tag);
buf.push(')');
let s: &'alloc str = code_transform.alloc_str(&buf);
pending_overwrites.push((start, end, s));

Save/Truncate for Nested Buffer Use

To build a temporary string inside a function already using buf, use save/truncate instead of allocating a second buffer:

let saved = buf.len();
buf.push_str("{ ");
for (i, prop) in props.iter().enumerate() {
    if i > 0 { buf.push_str(", "); }
    buf.push_str(prop);
}
buf.push_str(" }");
let result = code_transform.alloc_str(&buf[saved..]);
buf.truncate(saved); // restore buf to previous state

Avoids per-element heap allocation when building intermediate strings like hoisted props.

4. Object Pooling

StateStack (per-element state during tree walk) contains multiple Vec fields. Pool instead of allocating/dropping per element:

// Take from pool — Vecs retain capacity from previous use:
fn take_state(&mut self, id: u32) -> StateStack {
    if let Some(mut s) = self.state_pool.pop() {
        s.reset(id);  // .clear() on all Vecs — retains capacity
        s
    } else {
        StateStack { id, ..Default::default() }
    }
}

// Return to pool after element close:
fn return_state(&mut self, state: StateStack) {
    self.state_pool.push(state);
}

Apply to any struct with inner collections repeatedly created/dropped in a loop. Vec::clear() retains allocated capacity.

5. Borrow Source Instead of Cloning

ctx.input holds the full source text. Borrow slices directly instead of cloning:

// BAD: heap allocation just to read
let name: String = ctx.input[start..end].to_string();
buf.push_str(&name);

// GOOD: zero-cost borrow
let name: &str = &ctx.input[start as usize..end as usize];
buf.push_str(name);

For struct fields, prefer &'alloc str (bump-allocated) when the struct's lifetime allows. If adding a lifetime would cascade through too many types, String is acceptable.

6. Static Fast Paths

For functions frequently returning one of a small set of constants, return &'static str directly. &'static str coerces to &'alloc str, so static constants can be used anywhere bump-allocated strings are expected.

// Common close strings — no bump allocation needed
let close_str: &'alloc str = if patch_flag.0 == 0 && !is_block_root {
    if needs_array { "])" } else { ")" }  // &'static str coerces to &'alloc str
} else {
    // Rare case: build dynamically
    buf.clear();
    write_patch_flag_suffix(buf, patch_flag, &dynamic_props);
    code_transform.alloc_str(buf)
};

7. Pre-size Collections

Use with_capacity when expected size is known or estimable:

pending_overwrites: Vec::with_capacity(512),
pending_prepend_lefts: Vec::with_capacity(256),
buf: String::with_capacity(128),

Over-estimating slightly is cheaper than re-allocating.

8. Reduce Work, Not Just Speed

Once allocation and batching are optimized, further gains come from doing less work:

• Skip expensive operations for trivial cases — e.g., don't sort prop indices when all props have the same priority, don't run OXC parser for a bare identifier binding
• Early-return fast paths — e.g., skip Vec allocation + sort + clone when all element props are static (no directives)
• Merge redundant operations — e.g., combine two adjacent overwrites (tag name + props) into a single overwrite when both are known at the same time
• Cache/deduplicate repeated computations — e.g., resolved_components_set for component dedup
• Short-circuit early when results are known

9. Bulk-Copy String Processing

When processing strings character-by-character (e.g., escaping), prefer a bulk-copy pattern that tracks unmodified regions and copies them in one push_str call:

fn escape_js_string_into(buf: &mut String, s: &str) {
    let mut last_copy_end = 0;
    for (i, ch) in s.char_indices() {
        let replacement = match ch {
            '"' => "\\\"",
            '\\' => "\\\\",
            '\n' => "\\n",
            _ => continue,
        };
        buf.push_str(&s[last_copy_end..i]); // bulk copy unmodified region
        buf.push_str(replacement);
        last_copy_end = i + ch.len_utf8();
    }
    buf.push_str(&s[last_copy_end..]); // copy remaining
}

10. Benchmarking Methodology

When comparing against another compiler (e.g., Vue's @vue/compiler-sfc):

• Ensure feature parity — if one compiler generates source maps and the other doesn't, you're not comparing the same work
• Source maps are expensive — VLQ encoding + JSON serialization + base64 can consume 30-40% of compile time
• NAPI overhead is fixed — allocator creation + JS↔Rust marshalling adds ~7μs per call
• Profile in release mode — debug builds are 10-50x slower

Agent Profiling via MCP (hotpath)

pnpm run profile:hotpath:mcp    # Start with MCP endpoint at http://localhost:6771/mcp
pnpm run profile:hotpath        # Timing hotspots (no MCP)
pnpm run profile:hotpath:alloc  # Timing + allocation hotspots

Agent MCP config template: mcp/hotpath.mcp.json

11. CodeTransform Optimization History