[utils] add ArrayVec

[andresilva]

This PR adds ArrayVec<T, N>, a fixed-capacity inline vector that stores up to N elements without heap-allocating the backing storage. This is useful for small, bounded buffers where the maximum length is known at compile time. Capacity is capped at u16::MAX to prevent accidentally large inline values. The type uses unsafe partial-initialization internally (to avoid a T: Default bound) but exposes a fully safe public API.

The implementation covers the core Vec-like surface: push, pop, insert, remove, swap_remove, resize, truncate, extend, iteration, and conversions to/from Vec, slices, and arrays. An array_vec! macro provides convenient construction with inferred capacity.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	commonware-mcp	f53f4d9	Apr 07 2026, 11:25 AM

[cloudflare-workers-and-pages]

Deploying monorepo with    Cloudflare Pages

Latest commit:	f53f4d9
Status:	✅  Deploy successful!
Preview URL:	https://8ec5c483.monorepo-eu0.pages.dev
Branch Preview URL:	https://andre-stack-vec.monorepo-eu0.pages.dev

View logs

[clabby]

Is there a reason you opted to have our own implementation over using the arrayvec crate?

It also may be better to just use smallvec for this usecase, curious your thoughts. While it can spill over on to the heap unlike arrayvec / your impl, it should be roughly as efficient for the fixed size case while offering us a bit more flexibility to fit with often-small-but-dynamic cases as well.

[andresilva]

I don't really have an argument for not using arrayvec, in fact looking at it now the implementation is quite similar (although with a smaller API). I guess the only argument is that it's one less dependency to include, but I think arrayvec is probably already in our dependency tree (transitively). Will defer to @patrick-ogrady on this, am fine with just using arrayvec directly or just re-exporting it here.

I am worried that smallvec, or generally automatically spilling over to the heap, can mask pathological cases where you "thought" something was small but it actually isn't. smallvec is definitely more practical to use though.

[andresilva]

more flexibility to fit with often-small-but-dynamic cases as well

I guess this makes sense if it's just used as an optimization, where the size bound is more like a hint.

[clabby]

Admittedly I haven't benchmarked smallvec vs. arrayvec when they're both in-bounds of the stack allocated array, though if they perform similarly, smallvec does provide an API we could use to create a wrapper type that panics when a spill-over is attempted.

That said, both are already in the monorepo's dependency tree. We could just re-export both crates' types?

[clabby]

related #2343

[andresilva]

Thinking a bit more about this and after talking to @clabby, I think we should probably just re-export SmallVec:

• it's already on our dependency tree
• it's probably going to be more useful to us in practice than ArrayVec
• performance difference is probably negligible compared to ArrayVec, there's a branch before every operation to check whether we're inline or heap, but the branch predictor probably reduces that cost to ~0
• I'm not sure there's a lot of places where we can actually enforce strict bounds at compile time, for example in p2p, even stuff like max number of connections will be configured dynamically at runtime in most cases
• if at some point we actually have use cases for ArrayVec we can just re-export it as well (it's also already in our dependency tree!). I guess cryptography would probably be the place where we can actually use ArrayVec.

[codecov]

Codecov Report

❌ Patch coverage is 98.75691% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.74%. Comparing base (10fa6f2) to head (f53f4d9).
⚠️ Report is 142 commits behind head on main.

Files with missing lines	Patch %	Lines
utils/src/vec/array.rs	98.75%	8 Missing and 1 partial ⚠️

@@           Coverage Diff            @@
##             main    #3550    +/-   ##
========================================
  Coverage   95.74%   95.74%            
========================================
  Files         438      439     +1     
  Lines      158111   158835   +724     
  Branches     3707     3725    +18     
========================================
+ Hits       151382   152081   +699     
- Misses       5543     5564    +21     
- Partials     1186     1190     +4     

Files with missing lines	Coverage Δ
utils/src/vec/non_empty.rs	97.00% <ø> (ø)
utils/src/vec/array.rs	98.75% <98.75%> (ø)

... and 7 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 10fa6f2...f53f4d9. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.